riffer 0.48.0 → 0.49.0

data/sig/generated/riffer/providers/finish_reason.rbs

@@ -1,18 +1,12 @@
 # Generated from lib/riffer/providers/finish_reason.rb with RBS::Inline
 
-# Normalized reason an LLM call finished, paired with the provider's raw
-# wire value. +reason+ carries the same meaning for every provider.
 class Riffer::Providers::FinishReason
-  # The normalized vocabulary every provider maps into.
   VALUES: Array[Symbol]
 
-  # The normalized reason.
   attr_reader reason: Symbol
 
-  # The provider's raw finish-reason value, when one exists on the wire.
   attr_reader raw: String?
 
-  # Raises Riffer::ArgumentError when +reason+ is outside VALUES.
   # --
   # : (reason: Symbol, ?raw: String?) -> void
   def initialize: (reason: Symbol, ?raw: String?) -> void

data/sig/generated/riffer/providers/gemini/client.rbs

@@ -1,17 +1,7 @@
 # Generated from lib/riffer/providers/gemini/client.rb with RBS::Inline
 
-# HTTP transport for the Gemini REST API. Riffer builds one from the
-# configured +api_key+ by default; construct your own to tune the HTTP knobs
-# and assign it to <tt>Riffer.config.gemini.client</tt>. Any object
-# implementing +post+ and +post_stream+ with these contracts works there —
-# the class is a default implementation, not a required base.
-#
-#   Riffer.configure do |config|
-#     config.gemini.client = Riffer::Providers::Gemini::Client.new(
-#       api_key: ENV["GEMINI_API_KEY"],
-#       read_timeout: 120
-#     )
-#   end
+# <tt>Riffer.config.gemini.client</tt> accepts any object implementing +post+ and +post_stream+
+# with these contracts; this class is the default, not a required base.
 class Riffer::Providers::Gemini::Client
   @proxy_port: Integer?
 
@@ -36,15 +26,12 @@ class Riffer::Providers::Gemini::Client
   # : (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
   def initialize: (?api_key: String?, ?base_url: String, ?open_timeout: Integer, ?read_timeout: Integer, ?write_timeout: Integer?, ?proxy_address: String?, ?proxy_port: Integer?) -> void
 
-  # POSTs a JSON body to an API path and returns the parsed response hash.
-  # Raises Riffer::Error when the API responds with a non-success status.
+  # Raises Riffer::Error on a non-success status.
   # --
   # : (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
   def post: (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
 
-  # POSTs a JSON body to an API path, yielding raw response body chunks as
-  # they arrive. Raises Riffer::Error when the API responds with a
-  # non-success status.
+  # Raises Riffer::Error on a non-success status.
   # --
   # : (String, Hash[Symbol, untyped]) { (String) -> void } -> void
   def post_stream: (String, Hash[Symbol, untyped]) { (String) -> void } -> void

data/sig/generated/riffer/providers/gemini.rbs

@@ -1,12 +1,10 @@
 # Generated from lib/riffer/providers/gemini.rb with RBS::Inline
 
-# Google Gemini provider for Gemini models via the Gemini REST API.
 class Riffer::Providers::Gemini < Riffer::Providers::Base
   VALID_MODEL_PATTERN: Regexp
 
   FINISH_REASONS: Hash[String, Symbol]
 
-  # The GenAI semconv well-known provider name.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
@@ -49,14 +47,10 @@ class Riffer::Providers::Gemini < Riffer::Providers::Base
   # : (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (Hash[Symbol, untyped]) -> Riffer::Providers::FinishReason?
 
-  # Gemini reports STOP even when the candidate carries functionCall parts,
-  # so tool-call presence overrides the raw value.
   # --
   # : (String?, tool_calls: bool) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (String?, tool_calls: bool) -> Riffer::Providers::FinishReason?
 
-  # Gemini reports thinking tokens outside +candidatesTokenCount+;
-  # TokenUsage's output includes them.
   # --
   # : (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage
   def build_token_usage: (Hash[Symbol, untyped]) -> Riffer::Providers::TokenUsage

data/sig/generated/riffer/providers/mock.rbs

@@ -1,6 +1,5 @@
 # Generated from lib/riffer/providers/mock.rb with RBS::Inline
 
-# Mock provider for mocking LLM responses in tests; no external gems required.
 class Riffer::Providers::Mock < Riffer::Providers::Base
   @stubbed_responses: Array[Hash[Symbol, untyped]]
 
@@ -8,49 +7,24 @@ class Riffer::Providers::Mock < Riffer::Providers::Base
 
   @responses: Array[Hash[Symbol, untyped]]
 
-  # 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: (?String?) -> singleton(Riffer::Skills::Adapter)
 
-  # The GenAI semconv well-known provider name.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
 
-  # Array of recorded method calls for assertions.
   attr_reader calls: Array[Hash[Symbol, untyped]]
 
-  # +responses:+ pre-configures canned responses (same shape as
-  # +#stub_response+) for standalone use; agent tests queue responses on
-  # <tt>agent.provider</tt> via +#stub_response+ instead.
-  #
-  #   Riffer::Providers::Mock.new(responses: [
-  #     {content: "", tool_calls: [{name: "tool_a", arguments: "{}"}]},
-  #     {content: "Final answer"}
-  #   ])
-  #
   # --
   # : (?responses: Array[Hash[Symbol, untyped]]) -> void
   def initialize: (?responses: Array[Hash[Symbol, untyped]]) -> void
 
-  # Stubs the next response; call repeatedly to queue several. +finish_reason+
-  # defaults to +:tool_calls+ when tool calls are present, else +:stop+.
-  #
-  #   provider.stub_response("Hello")
-  #   provider.stub_response("", tool_calls: [{name: "my_tool", arguments: '{"key":"value"}'}])
-  #   provider.stub_response("Final response",
-  #                          token_usage: Riffer::Providers::TokenUsage.new(input_tokens: 10, output_tokens: 5))
-  #   provider.stub_response("Truncated...", finish_reason: :length)
-  #   provider.stub_response("Answer", reasoning: [{type: :text, text: "Thinking...", format: "mock-v1"}])
-  #
   # --
   # : (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?, ?reasoning: Array[Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart]) -> void
   def stub_response: (String, ?tool_calls: Array[Hash[Symbol, untyped]], ?token_usage: Riffer::Providers::TokenUsage?, ?finish_reason: Symbol?, ?reasoning: Array[Hash[Symbol, untyped] | Riffer::Messages::Assistant::ReasoningPart]) -> void
 
-  # Clears all stubbed responses.
-  #
   # --
   # : () -> void
   def clear_stubs: () -> void

data/sig/generated/riffer/providers/open_ai.rbs

@@ -1,15 +1,12 @@
 # Generated from lib/riffer/providers/open_ai.rb with RBS::Inline
 
-# OpenAI provider for GPT models. Requires the +openai+ gem.
 class Riffer::Providers::OpenAI < Riffer::Providers::Base
   WEB_SEARCH_TOOL_TYPE: String
 
-  # The Responses API has no finish_reason field. The response +status+ is
-  # the primary signal; an +incomplete+ status is only meaningful together
-  # with <tt>incomplete_details.reason</tt>, so that branch nests one level.
+  # The Responses API has no finish_reason field, and an +incomplete+ status is only meaningful
+  # together with <tt>incomplete_details.reason</tt>.
   FINISH_REASONS: Hash[String, Symbol | Hash[String, Symbol]]
 
-  # The GenAI semconv well-known provider name.
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
@@ -28,9 +25,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : () -> untyped
   def global_client: () -> untyped
 
-  # Compacted so an unset value stays absent: the SDK reads +OPENAI_API_KEY+ /
-  # +OPENAI_BASE_URL+ only for a missing argument, and an explicit nil would
-  # suppress that fallback.
   # --
   # : () -> untyped
   def build_client: () -> untyped
@@ -59,7 +53,6 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
-  # The nested field that names the cause behind an ambiguous status.
   # --
   # : (untyped, String) -> String?
   def finish_detail: (untyped, String) -> String?

data/sig/generated/riffer/providers/open_router.rbs

@@ -1,15 +1,17 @@
 # Generated from lib/riffer/providers/open_router.rb with RBS::Inline
 
-# 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+ resolves from config, then
-# +OPENROUTER_API_KEY+.
 class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   BASE_URL: String
 
   FINISH_REASONS: Hash[String, Symbol]
 
-  # The GenAI semconv well-known provider name.
+  REASONING_TYPES: Hash[String, Symbol]
+
+  # The +reasoning_details+ formats OpenRouter documents. Only parts tagged with
+  # one of them are replayed, so parts from other adapters, or with no format,
+  # never reach the request.
+  REASONING_FORMATS: Array[String]
+
   # --
   # : () -> String
   def self.semconv_provider_name: () -> String
@@ -28,11 +30,6 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : () -> untyped
   def global_client: () -> untyped
 
-  # Deliberately not compacted: this borrows the OpenAI SDK to talk to a
-  # different vendor, so omitting an unset +api_key+ would let the SDK fall
-  # back to +OPENAI_API_KEY+ and send an OpenAI credential to OpenRouter.
-  # Passing nil raises in the SDK instead. +OPENROUTER_API_KEY+ is read here
-  # rather than left to the SDK for the same reason.
   # --
   # : () -> untyped
   def build_client: () -> untyped
@@ -57,14 +54,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped) -> Riffer::Providers::FinishReason?
   def extract_finish_reason: (untyped) -> Riffer::Providers::FinishReason?
 
-  # +native+ is the upstream model's own finish reason, which OpenRouter
-  # reports alongside its normalized one; it wins as +raw+ when present.
   # --
   # : (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
   def build_finish_reason: (untyped, ?native: untyped) -> Riffer::Providers::FinishReason?
 
-  # +native_finish_reason+ is outside the OpenAI schema, so it is only
-  # reachable through the SDK model's raw data hash.
   # --
   # : (untyped) -> untyped
   def native_finish_reason: (untyped) -> untyped
@@ -77,6 +70,20 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
   def extract_tool_calls: (untyped) -> Array[Riffer::Messages::Assistant::ToolCall]
 
+  # --
+  # : (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+  def extract_reasoning: (untyped) -> Array[Riffer::Messages::Assistant::ReasoningPart]
+
+  # The openai gem's typed models strip fields outside OpenAI's spec, so
+  # +reasoning_details+ is only reachable through the model's raw data hash.
+  # --
+  # : (untyped) -> Array[Hash[Symbol, untyped]]?
+  def reasoning_details: (untyped) -> Array[Hash[Symbol, untyped]]?
+
+  # --
+  # : (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
+  def build_reasoning_part: (Hash[Symbol, untyped]) -> Riffer::Messages::Assistant::ReasoningPart?
+
   # --
   # : (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
   def execute_stream: (Hash[Symbol, untyped], Riffer::Providers::_EventSink) -> void
@@ -93,6 +100,14 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_reasoning_delta: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
 
+  # OpenRouter streams one reasoning block as many fragments sharing an
+  # +index+: prose and payload arrive in pieces to concatenate, while the
+  # signature, id, and format arrive once, often on the last fragment. Keying
+  # on +type+ as well keeps index-less fragments of different kinds apart.
+  # --
+  # : (Hash[untyped, Hash[Symbol, untyped]], Hash[Symbol, untyped]) -> void
+  def accumulate_reasoning_detail: (Hash[untyped, Hash[Symbol, untyped]], Hash[Symbol, untyped]) -> void
+
   # --
   # : (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
   def handle_tool_call_deltas: (untyped, state: Hash[Symbol, untyped], yielder: Riffer::Providers::_EventSink) -> void
@@ -113,6 +128,10 @@ class Riffer::Providers::OpenRouter < Riffer::Providers::Base
   # : (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
   def convert_assistant_to_chat_completions_format: (Riffer::Messages::Assistant) -> Hash[Symbol, untyped]
 
+  # --
+  # : (Riffer::Messages::Assistant::ReasoningPart) -> Hash[Symbol, untyped]
+  def convert_reasoning_part_to_detail: (Riffer::Messages::Assistant::ReasoningPart) -> Hash[Symbol, untyped]
+
   # --
   # : (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]
   def convert_file_part_to_chat_completions_format: (Riffer::Messages::User::FilePart) -> Hash[Symbol, untyped]

data/sig/generated/riffer/providers/repository.rbs

@@ -1,8 +1,5 @@
 # Generated from lib/riffer/providers/repository.rb with RBS::Inline
 
-# Resolves provider classes by identifier, combining the built-in REPO with
-# consumer registrations added through +register+. Registration is not
-# synchronized — register during boot, before concurrent generation begins.
 module Riffer::Providers::Repository
   @registrations: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
@@ -10,29 +7,20 @@ module Riffer::Providers::Repository
 
   REPO: Hash[Symbol, ^() -> singleton(Riffer::Providers::Base)]
 
-  # Registers a custom provider under +identifier+, resolved lazily by the block.
-  # Takes precedence over a built-in sharing the identifier.
-  #
-  #   Riffer::Providers::Repository.register(:jane) { MyApp::JaneProvider }
-  #
+  # Not synchronized — register during boot, before concurrent generation
+  # begins.
   # --
   # : ((String | Symbol)) { () -> singleton(Riffer::Providers::Base) } -> void
   def register: (String | Symbol) { () -> singleton(Riffer::Providers::Base) } -> void
 
-  # Removes a custom registration by identifier, leaving any built-in of the
-  # same name intact.
   # --
   # : ((String | Symbol)) -> void
   def unregister: (String | Symbol) -> void
 
-  # Finds a provider class by identifier, preferring a custom registration over
-  # a built-in of the same name.
-  #
   # --
   # : ((String | Symbol)) -> singleton(Riffer::Providers::Base)?
   def find: (String | Symbol) -> singleton(Riffer::Providers::Base)?
 
-  # Returns the registry identifier for a provider class, or nil when unregistered.
   # --
   # : (singleton(Riffer::Providers::Base)) -> Symbol?
   def key_for: (singleton(Riffer::Providers::Base)) -> Symbol?

data/sig/generated/riffer/providers/token_usage.rbs

@@ -1,46 +1,37 @@
 # Generated from lib/riffer/providers/token_usage.rb with RBS::Inline
 
-# Normalized token usage for an LLM API call. Buckets carry the same
-# meaning for every provider.
 class Riffer::Providers::TokenUsage
-  # Builds a TokenUsage from a hash, or returns +usage+ unchanged when it is
-  # already a TokenUsage.
   # --
   # : ((Hash[Symbol, untyped] | Riffer::Providers::TokenUsage)) -> Riffer::Providers::TokenUsage
   def self.from_hash: (Hash[Symbol, untyped] | Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
 
-  # Number of tokens entering the context window, including cache reads and writes.
+  # Normalized across providers: includes cache reads and writes.
   attr_reader input_tokens: Integer
 
-  # Number of tokens generated by the model, including reasoning/thinking tokens.
+  # Includes reasoning/thinking tokens.
   attr_reader output_tokens: Integer
 
-  # Subset of +input_tokens+ written to the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader cache_write_tokens: Integer?
 
-  # Subset of +input_tokens+ read from the provider's prompt cache, when the provider reports it.
+  # Subset of +input_tokens+.
   attr_reader cache_read_tokens: Integer?
 
-  # Cost of the call, set when the model is priced. For observability, not billing.
+  # For observability, not billing.
   attr_reader cost: Float?
 
   # --
   # : (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void
   def initialize: (input_tokens: Integer, output_tokens: Integer, ?cache_write_tokens: Integer?, ?cache_read_tokens: Integer?, ?cost: Float?) -> void
 
-  # Returns the total number of tokens (input + output).
-  #
   # --
   # : () -> Integer
   def total_tokens: () -> Integer
 
-  # Combines two TokenUsage objects for cumulative tracking.
-  #
   # --
   # : (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
   def +: (Riffer::Providers::TokenUsage) -> Riffer::Providers::TokenUsage
 
-  # Converts the token usage to a hash; cache tokens and cost are omitted when nil.
   # --
   # : () -> Hash[Symbol, (Integer | Float)]
   def to_h: () -> Hash[Symbol, Integer | Float]

data/sig/generated/riffer/registrable.rbs

@@ -1,68 +1,29 @@
 # Generated from lib/riffer/registrable.rb with RBS::Inline
 
-# Registry of a class's direct subclasses, keyed by identifier. Extend it
-# onto a base class to look up subclasses in constant time via +find+ and +all+.
-# Subclasses join implicitly by inheriting; +register+ adds one explicitly, for
-# ephemeral classes a test suite builds and tears down. Registration is not
-# synchronized — register during boot or from a single-threaded test, before
-# concurrent lookups begin.
-#
-#   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]?
 
   @explicit_registrations: Hash[String, Class]?
 
-  # Finds a registered subclass by identifier, or +nil+ when none matches.
-  # Implicit registration covers only *named direct* subclasses: grandchildren
-  # are not visible to a grandparent's +find+ (call +find+ on their direct
-  # parent instead), anonymous classes are never registered implicitly, and a
-  # subclass whose name no longer resolves back to it is dropped at the next
-  # registry rebuild. Duplicate identifiers raise
-  # Riffer::DuplicateIdentifierError at first lookup.
-  #
   # --
   # : (String | Symbol) -> Class?
   def find: (String | Symbol) -> Class?
 
-  # Returns all registered subclasses, implicit and explicit. Carries the same
-  # registration rules as +find+.
-  #
   # --
   # : () -> Array[Class]
   def all: () -> Array[Class]
 
-  # Registers a direct subclass under its +identifier+, whether or not it is
-  # named — unlike implicit registration, it survives a name that no longer
-  # resolves, so an ephemeral class stays findable until +unregister+. Prefer
-  # Riffer::Testing for ordinary test setup, which stubs and cleans up
-  # automatically.
-  #
-  # Raises Riffer::ArgumentError when the identifier is blank or the class is
-  # not a direct subclass, and Riffer::DuplicateIdentifierError when the
-  # identifier is already taken — including by this same class.
-  #
   # --
   # : (Class) -> void
   def register: (Class) -> void
 
-  # Removes an explicit registration of +klass+, leaving implicit registrations
-  # untouched.
   # --
   # : (Class) -> void
   def unregister: (Class) -> void
 
   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
@@ -79,12 +40,6 @@ module Riffer::Registrable : Class
   # : () -> Hash[String, Class]
   def build_identifier_registry: () -> Hash[String, Class]
 
-  # Class#subclasses keeps returning superseded generations of a reloaded or
-  # stubbed class, so a subclass counts only while its own name still resolves
-  # back to it. An anonymous class has no name to resolve and is skipped even
-  # with an explicit identifier — the MCP factory and serializer shells
-  # synthesize short-lived anonymous classes whose registration would flake
-  # with GC timing.
   # --
   # : (Class) -> bool
   def live?: (Class) -> bool

data/sig/generated/riffer/runner/fibers.rbs

@@ -1,11 +1,5 @@
 # Generated from lib/riffer/runner/fibers.rb with RBS::Inline
 
-# Processes items concurrently using fibers via the +async+ gem.
-# +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.
-# Joins the current reactor task when one is already running, and otherwise
-# starts its own.
 class Riffer::Runner::Fibers < Riffer::Runner
   @max_concurrency: Integer?
 

data/sig/generated/riffer/runner/sequential.rbs

@@ -1,6 +1,5 @@
 # Generated from lib/riffer/runner/sequential.rb with RBS::Inline
 
-# 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/sig/generated/riffer/runner/threaded.rbs

@@ -1,8 +1,5 @@
 # Generated from lib/riffer/runner/threaded.rb with RBS::Inline
 
-# 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
   @max_concurrency: Integer
 

data/sig/generated/riffer/runner.rbs

@@ -1,9 +1,6 @@
 # Generated from lib/riffer/runner.rb with RBS::Inline
 
-# 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.
   # --
   # : (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]
   def map: (Array[untyped], context: Riffer::Agent::Context?) { (untyped) -> untyped } -> Array[untyped]

data/sig/generated/riffer/skills/activate_tool.rbs

@@ -1,9 +1,6 @@
 # Generated from lib/riffer/skills/activate_tool.rb with RBS::Inline
 
-# 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
-  # Activates a skill by name and returns its wrapped body, or a short pointer when the skill is already active.
   # --
   # : (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response
   def call: (context: Riffer::Agent::Context?, name: String) -> Riffer::Tools::Response

data/sig/generated/riffer/skills/adapter.rbs

@@ -1,28 +1,20 @@
 # Generated from lib/riffer/skills/adapter.rb with RBS::Inline
 
-# 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)
 
   # --
   # : (skill_activate_tool: singleton(Riffer::Tool)) -> void
   def initialize: (skill_activate_tool: singleton(Riffer::Tool)) -> void
 
-  # Renders a skill catalog section for the system prompt.
   # --
   # : (Array[Riffer::Skills::Frontmatter]) -> String
   def render_catalog: (Array[Riffer::Skills::Frontmatter]) -> String
 
-  # Renders an activated skill body wrapped in identifying tags.
   # --
   # : (Riffer::Skills::Frontmatter, String) -> String
   def render_activation: (Riffer::Skills::Frontmatter, String) -> String
 
-  # The behavioral instructions rendered alongside the catalog.
   # --
   # : () -> String
   def catalog_instructions: () -> String

data/sig/generated/riffer/skills/backend.rbs

@@ -1,21 +1,16 @@
 # Generated from lib/riffer/skills/backend.rb with RBS::Inline
 
-# 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: String
 
   def initialize: () -> untyped
 
-  # Returns frontmatter for all available skills; called once at the start of
-  # generate/stream.
   # --
   # : () -> Array[Riffer::Skills::Frontmatter]
   def list_skills: () -> Array[Riffer::Skills::Frontmatter]
 
-  # Returns the full SKILL.md body (without frontmatter) for a skill. Raises
-  # Riffer::ArgumentError if the skill is not found.
+  # Returns the SKILL.md body without frontmatter. Raises Riffer::ArgumentError
+  # if the skill is not found.
   # --
   # : (String) -> String
   def read_skill: (String) -> String

data/sig/generated/riffer/skills/config.rbs

@@ -1,12 +1,5 @@
 # Generated from lib/riffer/skills/config.rb with RBS::Inline
 
-# Configuration object for the skills block DSL.
-#
-#   skills do
-#     backend Riffer::Skills::FilesystemBackend.new(".skills")
-#     adapter Riffer::Skills::XmlAdapter
-#     activate ["code-review"]
-#   end
 class Riffer::Skills::Config
   @backend: (Riffer::Skills::Backend | Proc)?
 
@@ -20,37 +13,24 @@ class Riffer::Skills::Config
   # : () -> void
   def initialize: () -> void
 
-  # Gets or sets the skills backend (a Backend or a +context+-resolved Proc).
   # --
   # : (?(Riffer::Skills::Backend | Proc)?) -> (Riffer::Skills::Backend | Proc)?
   def backend: (?(Riffer::Skills::Backend | Proc)?) -> (Riffer::Skills::Backend | Proc)?
 
-  # 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: (?singleton(Riffer::Skills::Adapter)?) -> singleton(Riffer::Skills::Adapter)?
 
-  # 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: (?(Array[String] | Proc)?) -> (Array[String] | Proc)?
 
-  # 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: (?singleton(Riffer::Tool)?) -> singleton(Riffer::Tool)?
 
   private
 
-  # +dup+ would leave the copy sharing this one's activation list, so activating
-  # a skill on either would reach the other. DeepDup rebuilds the list and
-  # returns a Proc as-is, which has nothing to alias.
   # --
   # : (Riffer::Skills::Config) -> void
   def initialize_copy: (Riffer::Skills::Config) -> void