riffer-rig 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b5a8d6de921c08c1ddb5caa12c5e22e0b3a68f7d26160b6fc732b647209b963
-  data.tar.gz: a37ce48ed7e46d9bca9a00db9a46411ecc0187550d58627879e9d97d36789650
+  metadata.gz: 9d560ab0c2be62a87e8468ba302f443985cd5d92d4872de2073c5c77b672d83f
+  data.tar.gz: b75fe6a3d1a7f0c718405f619f2f56c20fe85282ddb94aff9c2beb853344c119
 SHA512:
-  metadata.gz: b2b6f88978aa64314fb2b420047f97332090c3f8f699caa01564cd1ebf78dd5d862a22dca60e8e0734db647e2506aafbc5bd4de7a1ee1d800ee6a6edf1688b74
-  data.tar.gz: 3d6a59d2a2fa892430ddec4682c29fcc934d8568a3827ecf99546ea064b9ec246a1c5dbd5e96a0848328017408d17be91944bd2e84fd1eaf65dcc7707cf74389
+  metadata.gz: a2ca46037680a034a31b977101a9c5b442fc21f56842cb3055f2163493d42eef2d92ccdbc53aa9bf5fd2749af6fcfd52fb6d74aecbea0da907a5bac3ecee7498
+  data.tar.gz: 4e531d3fee7fa1107e7d6a7c5d1fa064c4bbdf9e46763353332d4b9d9b57b6a37436d54326fe06e21248c147d99e15ddaac4a18b6ee8ffd34be4e29d733444ae

data/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.8.0](https://github.com/bottrall/riffer-rig/compare/v0.7.0...v0.8.0) (2026-10-02)
+
+
+### Features
+
+* discover rig.rb files with project trust and optional gem autoload ([#208](https://github.com/bottrall/riffer-rig/issues/208)) ([6ed818f](https://github.com/bottrall/riffer-rig/commit/6ed818f5b5d382b3a9c7d48ce667892b10190985))
+* truncate tool output and fit lines to the terminal width ([#209](https://github.com/bottrall/riffer-rig/issues/209)) ([3765de1](https://github.com/bottrall/riffer-rig/commit/3765de1f4392d903939c1458e843c2ca1e70112e))
+
+## [0.7.0](https://github.com/bottrall/riffer-rig/compare/v0.6.0...v0.7.0) (2026-09-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* Riffer::Rig::CodingAgent, REPL, TokenTally and the UI namespace are removed, and the old CLI is replaced by the dispatcher. Embed a Runtime through Riffer::Rig::Loader.runtime instead of CodingAgent; the terminal UI classes now live under Riffer::Rig::Terminal. The bash tool now errors when its context has no :cwd.
+* DEFAULT_MODEL is gone; with no model the Loader asks the host to onboard and the null host's refusal is a configuration error. The old Settings module API changes shape.
+* Riffer::Rig::Hosts::Base and Riffer::Rig::Events::Event are removed. A host is any object implementing the five host methods (Riffer::Rig::Hosts::_Host); drop the superclass. A custom event drops the superclass and super(), and includes Riffer::Rig::Events::Value for equality.
+
+### Features
+
+* /model switches the model for the current Runtime ([#193](https://github.com/bottrall/riffer-rig/issues/193)) ([f888972](https://github.com/bottrall/riffer-rig/commit/f8889722f62499f97ee34158826e9d00dd3d92ef))
+* bundle Agent Skills with /skill: commands over the skills seam ([#201](https://github.com/bottrall/riffer-rig/issues/201)) ([e14844d](https://github.com/bottrall/riffer-rig/commit/e14844d9c7c22dd85b3d4158892ec53bae736c6b))
+* bundle AGENTS.md as the agents_md prompt section ([#198](https://github.com/bottrall/riffer-rig/issues/198)) ([e2e9141](https://github.com/bottrall/riffer-rig/commit/e2e914195f7c15c75ee2ae6bb55d772d754a2f37))
+* bundle read, write, edit and bash as extensions ([#195](https://github.com/bottrall/riffer-rig/issues/195)) ([d5c9ffe](https://github.com/bottrall/riffer-rig/commit/d5c9ffe692abf5e5cab16af0686f96b040a6cbaa))
+* bundle the MCP client over the mcp seam ([#202](https://github.com/bottrall/riffer-rig/issues/202)) ([c2fc42f](https://github.com/bottrall/riffer-rig/commit/c2fc42ff873af8205f3a8042069a3dd5f27420e6))
+* isolate extension load errors and check requires ([#192](https://github.com/bottrall/riffer-rig/issues/192)) ([0aac3bf](https://github.com/bottrall/riffer-rig/commit/0aac3bf7d3b6ada84a4f38a40abc181f7d3f57c7)), closes [#114](https://github.com/bottrall/riffer-rig/issues/114)
+* lifecycle, vetoable and observe hooks plus the stream passthrough ([#194](https://github.com/bottrall/riffer-rig/issues/194)) ([206d349](https://github.com/bottrall/riffer-rig/commit/206d349a4967081961372d1692b0946663f32a10))
+* Loader builds a Runtime from settings, credentials and the bundle ([#205](https://github.com/bottrall/riffer-rig/issues/205)) ([01170fe](https://github.com/bottrall/riffer-rig/commit/01170fee282deae87aba1b8797cfe5cedc892deb)), closes [#123](https://github.com/bottrall/riffer-rig/issues/123)
+* namespaced extension settings ([#196](https://github.com/bottrall/riffer-rig/issues/196)) ([dc16a84](https://github.com/bottrall/riffer-rig/commit/dc16a8424ea00ea0b39323db97309c9c94224443)), closes [#117](https://github.com/bottrall/riffer-rig/issues/117)
+* rebuild the registrar in place ([#199](https://github.com/bottrall/riffer-rig/issues/199)) ([f4b742b](https://github.com/bottrall/riffer-rig/commit/f4b742b3f45a28f3c69d75a355c3a2880938de1b))
+* runtime commands with run_command and the command context ([#190](https://github.com/bottrall/riffer-rig/issues/190)) ([159d007](https://github.com/bottrall/riffer-rig/commit/159d0077b34773fadb2cc6f5f66622b12e4b7a0e)), closes [#111](https://github.com/bottrall/riffer-rig/issues/111)
+* snapshot and restore a Runtime ([#200](https://github.com/bottrall/riffer-rig/issues/200)) ([aaad579](https://github.com/bottrall/riffer-rig/commit/aaad5797e5e626b6f560b96a5f4cf1bf5bc379a3))
+* Terminal drives a Loader-built Runtime ([#206](https://github.com/bottrall/riffer-rig/issues/206)) ([f805db6](https://github.com/bottrall/riffer-rig/commit/f805db625e69f90c2dd343bbb7ca016aba7cecf0))
+* token tally and pricing behind the Runtime ([#189](https://github.com/bottrall/riffer-rig/issues/189)) ([1ccde0d](https://github.com/bottrall/riffer-rig/commit/1ccde0d1670feaa2a9b9c957bbe79fa80ca47d4f))
+
+
+### Bug Fixes
+
+* run steep check without attaching to a language server ([#197](https://github.com/bottrall/riffer-rig/issues/197)) ([4f0b92e](https://github.com/bottrall/riffer-rig/commit/4f0b92eeafcb4e4fb6d054c29d707fcfb39766d5))
+
+
+### Code Refactoring
+
+* interfaces over inheritance, POROs over hashes, new cops ([#204](https://github.com/bottrall/riffer-rig/issues/204)) ([7fda3e3](https://github.com/bottrall/riffer-rig/commit/7fda3e3ec79ea97479008127f0c153ce84b888d5))
+
 ## [0.6.0](https://github.com/bottrall/riffer-rig/compare/v0.5.0...v0.6.0) (2026-09-27)
 
 

data/README.md

@@ -26,9 +26,36 @@ Run the agent from any project directory:
 riffer
 ```
 
+The first run asks which model to use, as `provider/name` (for example `anthropic/claude-sonnet-4-6`), and saves the answer as `model` in `~/.riffer/settings.json`; it then asks for any missing credential ([Authentication](#authentication)). After that, `riffer` opens straight into the prompt. [Getting started](docs/GETTING_STARTED.md) walks through a first session.
+
+The model is the first of these that is set: `--model`, `RIFFER_MODEL`, `model` in `<cwd>/.riffer/settings.json`, then in `~/.riffer/settings.json` ([Configuration](docs/CONFIGURATION.md#model)).
+
+### Flags
+
+| Flag                    | Effect                                                                     |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `--model provider/name` | the model for this session, over `RIFFER_MODEL` and the settings            |
+| `--no-extensions`       | skips the [`rig.rb` files](docs/EXTENSIONS.md#the-rigrb-files) and gem autoload; the bundle still loads |
+| `--no-skills`           | leaves out [Agent Skills](docs/SKILLS.md)                                   |
+| `--no-agents-md`        | leaves out the [AGENTS.md](docs/INSTRUCTIONS.md#agentsmd) instructions      |
+| `--tools read,bash`     | only these tools, by identifier ([Tools](docs/TOOLS.md))                    |
+| `--max-steps N`         | stops a turn after `N` model calls                                          |
+| `-h`, `--help`          | prints the usage                                                            |
+
+`riffer -p` (one prompt, no terminal) and `riffer acp` (an editor's agent over stdio) are reserved: for now each prints the usage and exits with status 2.
+
+### In the session
+
+Type a prompt and press Enter; the reply streams in, with each tool call and the first line of its result, and every turn ends with a token line (`↑in · ↓out · session N tok`, plus the session cost when the model is [priced](docs/CONFIGURATION.md#models)).
+
+- Ctrl-C during a turn cancels it and returns to the prompt. Ctrl-C at the prompt asks for a second one, which exits.
+- `/exit` or `/quit` ends the session, as does Ctrl-D.
+- `/model provider/name` switches the model ([below](#switching-the-model)), and `/skill:<name> [text]` runs a skill ([Skills](docs/SKILLS.md)).
+- Any other `/name args` runs the Runtime command of that name, such as one an extension registers ([Extensions](docs/EXTENSIONS.md)); an unknown name is reported and nothing is sent to the model.
+
 ### Authentication
 
-`riffer-rig` talks to the provider named by the model's prefix — `anthropic/claude-sonnet-4-6`, the default, means Anthropic. Provide that provider's credentials in either of two ways:
+`riffer-rig` talks to the provider named by the model's prefix — `anthropic/claude-sonnet-4-6` means Anthropic. Provide that provider's credentials in either of two ways:
 
 - Set the provider's environment variables, or
 - Run `riffer` and paste each missing value when prompted on first launch. Secrets are saved to `~/.riffer/auth.json` (file permissions `600`); plain values such as an endpoint or region are saved to the `providers` block in `~/.riffer/settings.json`.
@@ -55,10 +82,16 @@ Each value resolves on its own: environment variable first, then the stored valu
 
 The flat `{"anthropic": "sk-…"}` shape earlier versions wrote is no longer read; paste the key again when prompted. [Providers](docs/PROVIDERS.md) has the full format.
 
+### Switching the model
+
+`/model provider/name` switches the model for the current session only, keeping the conversation so far — `/model openai/gpt-5`, say. The provider prefix is required: a bare name such as `/model sonnet` is rejected with the list of providers. `/model` alone shows the model in use. The switch is refused when the session has no credentials for the new provider, and it never changes `settings.json`; set `model` there to change the model new sessions start with ([Configuration](docs/CONFIGURATION.md#model)).
+
 ### Configuration
 
-- `AGENTS.md` — if present, an `AGENTS.md` in the current working directory and/or a global `~/.riffer/AGENTS.md` is loaded as additional context.
-- `~/.riffer/settings.json` — optional user settings. Every key is optional:
+- `AGENTS.md` — `~/.riffer/AGENTS.md` and an `AGENTS.md` in the current working directory or any directory above it, whichever exist, are re-read every turn as instructions that take precedence over the default norms ([Instructions](docs/INSTRUCTIONS.md#agentsmd)).
+- Skills — Agent Skills in `.agents/skills/` from the current working directory up to the repository root, and in `~/.agents/skills/`, are offered to the model, and each can be run with `/skill:<name>` ([Skills](docs/SKILLS.md)).
+- `RIFFER_MODEL` — the model for this run as `provider/name`, winning over the `model` setting. A bare name such as `sonnet` is rejected with the list of providers.
+- `~/.riffer/settings.json` — optional user settings, and `<cwd>/.riffer/settings.json` for one project, merged key by key with the project winning. Every key is optional:
 
   ```json
   {
@@ -75,7 +108,7 @@ The flat `{"anthropic": "sk-…"}` shape earlier versions wrote is no longer rea
   }
   ```
 
-  `models` holds pricing in USD per million tokens; a model without an entry shows no cost. `reasoning` is translated to the provider's own parameter — Anthropic accepts `low`, `medium`, `high`, `xhigh` and `max`; OpenAI and OpenRouter accept `low`, `medium`, `high` and `xhigh`. Omitting it, or supplying an unrecognised value, leaves the model's default reasoning behaviour unchanged.
+  `model` is the model new sessions start with; a host built on the [Loader](docs/EMBEDDING.md#building-a-runtime-with-the-loader) asks for one when none is set and writes the answer here. `extensions.disabled` (for example `["mcp"]`) leaves bundled extensions out. `models` prices each model in USD per million tokens; [Configuration](docs/CONFIGURATION.md) has every key. `reasoning` is translated to the provider's own parameter — Anthropic accepts `low`, `medium`, `high`, `xhigh` and `max`; OpenAI and OpenRouter accept `low`, `medium`, `high` and `xhigh`. Omitting it, or supplying an unrecognised value, leaves the model's default reasoning behaviour unchanged.
 
 ## Development
 
@@ -91,6 +124,7 @@ Every project chore is a script in `bin/`. The Rakefile behind them is an implem
 | `bin/rbs-watch` | Regenerate `sig/generated` whenever `lib/` changes                                             |
 | `bin/ci`        | Run everything CI runs, serially. Use before pushing                                           |
 | `bin/build`     | Build the gem into `pkg/`; the publish workflow runs this before `gem push`                    |
+| `bin/docs`      | Build the docs site and API reference into `_site/`; `bin/docs serve` serves it at http://localhost:8000 |
 | `bin/plans`     | Serve the building plans in `plans/` at http://localhost:8001                                  |
 
 ## Releasing

data/exe/riffer

@@ -5,4 +5,4 @@ require "bundler/setup" if File.exist?(File.expand_path("../Gemfile", __dir__))
 
 require_relative "../lib/riffer/rig"
 
-exit(Riffer::Rig::CLI.start)
+exit(Riffer::Rig::CLI.start(ARGV))

data/lib/riffer/rig/bundled/agents_md.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  AgentsMd = Riffer::Rig::Extension.new('agents_md') do |rig|
+    rig.prompt(:agents_md) { |runtime| Riffer::Rig::Prompts::AgentsMd.section(runtime.cwd) }
+  end #: Riffer::Rig::Extension
+end

data/lib/riffer/rig/bundled/bash.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  Bash = Riffer::Rig::Extension.new('bash') { |rig| rig.tool Riffer::Rig::Tools::Bash } #: Riffer::Rig::Extension
+end

data/lib/riffer/rig/bundled/edit.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  Edit = Riffer::Rig::Extension.new('edit') { |rig| rig.tool Riffer::Rig::Tools::Edit } #: Riffer::Rig::Extension
+end

data/lib/riffer/rig/bundled/mcp.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  Mcp = Riffer::Rig::Extension.new('mcp') do |rig|
+    rig.settings[:servers].to_h.each do |name, server|
+      rig.mcp(name.to_s, url: server.fetch(:url), headers: server[:headers].to_h.transform_keys(&:to_s))
+    end
+  end #: Riffer::Rig::Extension
+end

data/lib/riffer/rig/bundled/read.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  Read = Riffer::Rig::Extension.new('read') { |rig| rig.tool Riffer::Rig::Tools::Read } #: Riffer::Rig::Extension
+end

data/lib/riffer/rig/bundled/skills.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  Skills = Riffer::Rig::Extension.new('skills') do |rig|
+    rig.skills do |runtime|
+      Riffer::Skills::FilesystemBackend.new(*Riffer::Rig::Skills.directories(runtime.cwd))
+    end
+    rig.prompt(:skills) { nil }
+  end #: Riffer::Rig::Extension
+end

data/lib/riffer/rig/bundled/write.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  Write = Riffer::Rig::Extension.new('write') { |rig| rig.tool Riffer::Rig::Tools::Write } #: Riffer::Rig::Extension
+end

data/lib/riffer/rig/bundled.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Bundled
+  BY_NAME = {
+    read: Read, write: Write, edit: Edit, bash: Bash, agents_md: AgentsMd, skills: Skills, mcp: Mcp
+  }.freeze #: Hash[Symbol, Riffer::Rig::Extension]
+end

data/lib/riffer/rig/cli/flags.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'optparse'
+
+class Riffer::Rig::CLI::Flags
+  BANNER = <<~TEXT.chomp #: String
+    Usage: riffer [options]
+           riffer -p [prompt]   (not available yet)
+           riffer acp           (not available yet)
+  TEXT
+
+  # @dynamic model, extensions, skills, agents_md, tools, max_steps, help
+  attr_reader :model #: String?
+  attr_reader :extensions, :skills, :agents_md, :help #: bool
+  attr_reader :tools #: Array[String]?
+  attr_reader :max_steps #: Integer?
+
+  # @rbs argv: Array[String]
+  # @rbs return: Riffer::Rig::CLI::Flags | String
+  def self.parse(argv)
+    values = {} #: Hash[Symbol, untyped]
+    rest = parser.parse(argv, into: values)
+    return "unexpected argument: #{rest.join(' ')}" unless rest.empty?
+
+    new(
+      model: values[:model],
+      extensions: !values.key?(:'no-extensions'),
+      skills: !values.key?(:'no-skills'),
+      agents_md: !values.key?(:'no-agents-md'),
+      tools: values[:tools],
+      max_steps: values[:'max-steps'],
+      help: values.key?(:help)
+    )
+  rescue OptionParser::ParseError => e
+    e.message
+  end
+
+  # @rbs return: String
+  def self.usage
+    parser.help
+  end
+
+  # @rbs return: OptionParser
+  def self.parser
+    OptionParser.new do |parser|
+      parser.banner = BANNER
+      parser.separator('')
+      parser.on('--model PROVIDER/NAME', String, 'Model for this session, over RIFFER_MODEL and settings')
+      parser.on('--no-extensions', 'Skip extension files and autoload; the bundle still loads')
+      parser.on('--no-skills', 'Leave out Agent Skills')
+      parser.on('--no-agents-md', 'Leave out AGENTS.md instructions')
+      parser.on('--tools NAME,NAME', Array, 'Only these tools, by identifier')
+      parser.on('--max-steps N', Integer, 'Stop a turn after N model calls')
+      parser.on('-h', '--help', 'Show this help')
+    end
+  end
+  private_class_method :parser
+
+  # @rbs model: String?
+  # @rbs extensions: bool
+  # @rbs skills: bool
+  # @rbs agents_md: bool
+  # @rbs tools: Array[String]?
+  # @rbs max_steps: Integer?
+  # @rbs help: bool
+  # @rbs return: void
+  def initialize(model: nil, extensions: true, skills: true, agents_md: true, tools: nil, max_steps: nil, help: false)
+    @model = model
+    @extensions = extensions
+    @skills = skills
+    @agents_md = agents_md
+    @tools = tools&.freeze
+    @max_steps = max_steps
+    @help = help
+    freeze
+  end
+end

data/lib/riffer/rig/cli.rb

@@ -1,129 +1,92 @@
 # frozen_string_literal: true
 
-require 'io/console'
-
 module Riffer::Rig::CLI
   extend self
 
-  # @rbs output: IO
-  # @rbs input: IO
-  # @rbs model: String
-  # @rbs env: Riffer::Rig::Env
-  # @rbs return: Integer
-  def start(output: $stdout, input: $stdin, model: Riffer::Rig::Settings.model, env: Riffer::Rig::Env.new)
-    theme = Riffer::Rig::UI::Theme.for(output, env:)
+  PRINT_FLAGS = %w[-p --print].freeze #: Array[String]
 
-    provider = Riffer::Rig::Settings.provider_for(model)
+  ACP_COMMAND = 'acp'
 
-    if provider
-      values = credentials_for(provider, theme, output:, input:, env:)
-      return 1 if values.nil?
+  USAGE_ERROR = 2
 
-      Riffer::Rig::Credentials.apply(provider, values)
-    end
-
-    agent    = Riffer::Rig::CodingAgent.new
-    animator = Riffer::Rig::UI::Animator.new(io: output, theme:)
-
-    reveal_banner(theme, animator, model)
-
-    tally    = Riffer::Rig::TokenTally.new(pricing: Riffer::Rig::Settings.pricing_for(model))
-    smoother = Riffer::Rig::UI::Smoother.new(io: output, theme:)
-    renderer = Riffer::Rig::UI::Renderer.new(io: output, theme:, tally:, smoother:)
-    Riffer::Rig::REPL.new(agent:, renderer:, animator:, theme:, smoother:, input:, output:).run
-    0
+  # @rbs argv: Array[String]
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs error: IO
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs cwd: String
+  # @rbs home: String
+  # @rbs return: Integer
+  def start(
+    argv = ARGV,
+    input: $stdin,
+    output: $stdout,
+    error: $stderr,
+    env: Riffer::Rig::Env.load,
+    cwd: Dir.pwd,
+    home: Dir.home
+  )
+    return unavailable("riffer #{ACP_COMMAND}", error) if argv.first == ACP_COMMAND
+    return unavailable('riffer -p', error) if argv.intersect?(PRINT_FLAGS)
+
+    flags = Flags.parse(argv)
+    return refuse(flags, error) if flags.is_a?(String)
+    return help(output) if flags.help
+
+    terminal(flags, input:, output:, env:, cwd:, home:)
   end
 
   private
 
-  # @rbs provider: String
-  # @rbs theme: Riffer::Rig::UI::Theme
-  # @rbs output: IO
+  # @rbs flags: Riffer::Rig::CLI::Flags
   # @rbs input: IO
-  # @rbs env: Riffer::Rig::Env
-  # @rbs return: Hash[Symbol, String]?
-  def credentials_for(provider, theme, output:, input:, env:)
-    resolution = Riffer::Rig::Credentials.resolve(provider, host: Riffer::Rig::Hosts::Null.new, env:)
-    return resolution.values if resolution.missing.empty?
-
-    onboard(provider, resolution, theme, output:, input:)
-  end
-
-  # @rbs provider: String
-  # @rbs resolution: Riffer::Rig::Credentials::Resolution
-  # @rbs theme: Riffer::Rig::UI::Theme
   # @rbs output: IO
-  # @rbs input: IO
-  # @rbs return: Hash[Symbol, String]?
-  def onboard(provider, resolution, theme, output:, input:)
-    setup = Riffer::Rig::ProviderSetup.for(provider)
-    missing = setup.fields.select { |field| resolution.missing.include?(field.name) }
-
-    output.puts(theme.cyan('♪ welcome to riffer-rig ♪'))
-    output.puts(theme.grey("No #{provider} credentials found. Create them at #{setup.url || 'your provider'}"))
-
-    answers = missing.to_h { |field| [field.name, prompt(provider, field, theme, output:, input:)] }
-    if answers.values.any?(&:empty?)
-      env_vars = missing.flat_map(&:env).join(', ')
-      output.puts(theme.grey("Nothing entered. Set #{env_vars} or re-run riffer to try again."))
-      return nil
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs cwd: String
+  # @rbs home: String
+  # @rbs return: Integer
+  def terminal(flags, input:, output:, env:, cwd:, home:)
+    Riffer::Rig::Terminal.for(
+      input: input,
+      output: output,
+      version: Riffer::Rig::VERSION,
+      no_color: env.is_a?(Riffer::Rig::Env) && env.no_color
+    ).run do |host|
+      Riffer::Rig::Loader.runtime(
+        cwd: cwd,
+        host: host,
+        env: env,
+        home: home,
+        model: flags.model,
+        extensions: flags.extensions,
+        skills: flags.skills,
+        agents_md: flags.agents_md,
+        tools: flags.tools,
+        max_steps: flags.max_steps
+      )
     end
-
-    Riffer::Rig::Credentials.store(provider, answers)
-    output.puts(theme.grey("Saved under #{File.dirname(Riffer::Rig::Credentials::PATH)} (auth.json permissions 600)."))
-    resolution.values.merge(answers)
-  end
-
-  # @rbs provider: String
-  # @rbs field: Riffer::Rig::ProviderSetup::Field
-  # @rbs theme: Riffer::Rig::UI::Theme
-  # @rbs output: IO
-  # @rbs input: IO
-  # @rbs return: String
-  def prompt(provider, field, theme, output:, input:)
-    hint = field.secret ? " #{theme.grey('(hidden)')}" : ''
-    output.print("#{theme.pink('›')} Paste your #{provider} #{field.name}#{hint}: ")
-
-    answer = (field.secret ? read_secret(input) : input.gets).to_s.strip
-    output.puts
-    answer
   end
 
-  # @rbs input: IO
-  # @rbs return: String?
-  def read_secret(input)
-    return input.noecho(&:gets) if input.respond_to?(:noecho) && input.tty?
-
-    input.gets
+  # @rbs name: String
+  # @rbs error: IO
+  # @rbs return: Integer
+  def unavailable(name, error)
+    refuse("#{name} is not available yet", error)
   end
 
-  # @rbs theme: Riffer::Rig::UI::Theme
-  # @rbs animator: Riffer::Rig::UI::Animator
-  # @rbs model: String
-  # @rbs return: void
-  def reveal_banner(theme, animator, model)
-    loaded  = [Riffer::Rig::CodingAgent::GLOBAL_AGENTS_FILE, File.join(Dir.pwd, 'AGENTS.md')].select { |path| File.file?(path) }
-    context = loaded.empty? ? 'none' : loaded.join(', ')
-
-    animator.reveal(
-      [Riffer::Rig::UI::Banner.lines(
-        theme,
-        model: model,
-        cwd: Dir.pwd,
-        context: context,
-        skills: count_skills,
-        version: Riffer::Rig::VERSION
-      )]
-    )
+  # @rbs message: String
+  # @rbs error: IO
+  # @rbs return: Integer
+  def refuse(message, error)
+    error.puts("riffer: #{message}")
+    error.puts(Flags.usage)
+    USAGE_ERROR
   end
 
-  # @rbs return: String
-  def count_skills
-    dirs    = [Riffer::Rig::CodingAgent::GLOBAL_SKILLS_DIR, Riffer::Rig::CodingAgent::PROJECT_SKILLS_DIR.call]
-    backend = Riffer::Skills::FilesystemBackend.new(*dirs)
-    count   = backend.list_skills.length
-    count.zero? ? 'none' : count.to_s
-  rescue StandardError
-    'none'
+  # @rbs output: IO
+  # @rbs return: Integer
+  def help(output)
+    output.puts(Flags.usage)
+    0
   end
 end

data/lib/riffer/rig/command/context.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Command::Context
+  # @rbs @command: String
+  # @rbs @emit: ^(Riffer::Rig::Events::_Event) -> void
+  # @rbs @turn: ^(String) -> void
+
+  # @dynamic args, runtime, host, settings
+  attr_reader :args #: String
+  attr_reader :runtime #: Riffer::Rig::Runtime
+  attr_reader :host #: Riffer::Rig::Hosts::_Host
+  attr_reader :settings #: Hash[Symbol, untyped]
+
+  # @rbs command: String
+  # @rbs args: String
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs settings: Hash[Symbol, untyped]
+  # @rbs emit: ^(Riffer::Rig::Events::_Event) -> void
+  # @rbs turn: ^(String) -> void
+  # @rbs return: void
+  def initialize(command, args, runtime:, host:, settings:, emit:, turn:)
+    @command = command
+    @args = args
+    @runtime = runtime
+    @host = host
+    @settings = settings
+    @emit = emit
+    @turn = turn
+    freeze
+  end
+
+  # @rbs text: String
+  # @rbs return: nil
+  def say(text)
+    emit(Riffer::Rig::Events::CommandOutput.new(@command, text))
+  end
+
+  # @rbs event: Riffer::Rig::Events::_Event
+  # @rbs return: nil
+  def emit(event)
+    @emit.call(event)
+    nil
+  end
+
+  # @rbs text: String
+  # @rbs return: nil
+  def prompt(text)
+    @turn.call(text)
+    nil
+  end
+
+  # @rbs question: String?
+  # @rbs options: Array[String]?
+  # @rbs secret: bool
+  # @rbs return: String?
+  def ask(question = nil, options: nil, secret: false)
+    return unless host.capabilities.include?(:ask)
+
+    host.ask(question, options: options, secret: secret)
+  end
+
+  # @rbs question: String?
+  # @rbs return: bool
+  def confirm(question = nil)
+    return false unless host.capabilities.include?(:confirm)
+
+    host.confirm(question)
+  end
+end

data/lib/riffer/rig/command.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Riffer::Rig::Command
+  # @rbs @block: ^(Riffer::Rig::Command::Context) -> void
+
+  # @dynamic name, description, extension
+  attr_reader :name #: String
+  attr_reader :description #: String
+  attr_reader :extension #: String
+
+  # @rbs name: String
+  # @rbs description: String
+  # @rbs extension: String
+  # @rbs &block: (Riffer::Rig::Command::Context) -> void
+  # @rbs return: void
+  def initialize(name, description:, extension:, &block)
+    @name = name
+    @description = description
+    @extension = extension
+    @block = block
+    freeze
+  end
+
+  # @rbs ctx: Riffer::Rig::Command::Context
+  # @rbs return: void
+  def call(ctx)
+    @block.call(ctx)
+  end
+end

data/lib/riffer/rig/commands/model.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::Commands::Model
+  extend self
+
+  HINT = 'Use /model provider/name, with a provider from: ' \
+         "#{Riffer::Rig::Settings::PROVIDERS.join(', ')}".freeze #: String
+
+  SAVE_UNAVAILABLE = '/model --save is not available in this host'
+
+  # @rbs return: Riffer::Rig::Command
+  def command
+    Riffer::Rig::Command.new(
+      'model',
+      description: 'Switch the model for this session: /model provider/name',
+      extension: 'core'
+    ) { |ctx| run(ctx) }
+  end
+
+  # @rbs ctx: Riffer::Rig::Command::Context
+  # @rbs return: void
+  def run(ctx)
+    model = ctx.args.strip
+    return ctx.host.notify(SAVE_UNAVAILABLE, level: :error) if model.split.include?('--save')
+    return ctx.say("Model: #{ctx.runtime.model}") if model.empty?
+
+    provider = Riffer::Rig::Settings.provider_for(model)
+    return ctx.say(HINT) unless provider && Riffer::Providers::Repository.find(provider)
+
+    missing = missing_credentials(provider, ctx.runtime.credentials)
+    return ctx.host.notify(refusal(model, provider, missing), level: :error) unless missing.empty?
+
+    ctx.runtime.model = model
+    ctx.say("Model: #{model}")
+  end
+
+  private
+
+  # @rbs model: String
+  # @rbs provider: String
+  # @rbs missing: Array[Symbol]
+  # @rbs return: String
+  def refusal(model, provider, missing)
+    "Not switching to #{model}: #{provider} has no #{missing.join(', ')} in credentials"
+  end
+
+  # @rbs provider: String
+  # @rbs credentials: Hash[Symbol, Hash[Symbol, String]]
+  # @rbs return: Array[Symbol]
+  def missing_credentials(provider, credentials)
+    required = Riffer::Rig::ProviderSetup[provider]&.fields&.select(&:required) || []
+    required.map(&:name).reject { |name| credentials.dig(provider.to_sym, name) }
+  end
+end