riffer-rig 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a1580a7e4f2ed5e6d1f18714ef469b7d4623bec94552510a836a5f5e5664504
-  data.tar.gz: 7e871b6b1f8c9de6e3788979103f7afe65beea7a9c5fa7813e17b29e4e8eb528
+  metadata.gz: 52fc3da32f169222f7f3bac50e5ecb6d878fe46cf1955b00b218f26af043b2e9
+  data.tar.gz: a6a2c8c3c36fb9774550f2188d7cdfb529b5abb53805bd58eb31863f00c335c8
 SHA512:
-  metadata.gz: db021260a12a48c02bb6ff92278819416bcc267bd78015f01f80bd3a9ed64c585e37d17573a3ba47ba28d99bd0ef586665a465782d36a6a85231c08ad4a4fd51
-  data.tar.gz: 5ea0ed0a06d1a318267bd3d63b693f974ff8ca814e26be0eb5837cdac09527bea33a75357f7a1a11b419854ed72810a5d571c8508010e8bd62f327eb922f04eb
+  metadata.gz: 4fb9601edf932b84ee1c91b226d22814b8d80633e891ef3a3dc2436d59fc2ea617c53772ec2b9042362e937590a525f000dc6e85bb748b8bdd1ba32e017bc551
+  data.tar.gz: c51101a3560a43400edc5608e37f4615383cfdee22f8c2975b14e7d95a52bce08c063db1d2de108189e525ee1bf3f13377e4c3b22c9bef3b0a147298ac25f228

data/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## [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)
+
+
+### ⚠ BREAKING CHANGES
+
+* the flat `{"anthropic": "sk-..."}` auth.json shape is no longer read, with no migration. Stored keys must be re-entered or rewritten as `{"anthropic": {"type": "api_key", "api_key": "sk-..."}}`.
+* Riffer::Rig::Host is removed. A host subclasses Riffer::Rig::Hosts::Base and implements all five methods; the null host is Riffer::Rig::Hosts::Null.
+
+### Features
+
+* add the rig event vocabulary and close ([#179](https://github.com/bottrall/riffer-rig/issues/179)) ([35bfa6e](https://github.com/bottrall/riffer-rig/commit/35bfa6e5dc1dc9825fd03843a4e69ec24e675b66))
+* cancel a running turn from any thread ([#186](https://github.com/bottrall/riffer-rig/issues/186)) ([ec68188](https://github.com/bottrall/riffer-rig/commit/ec68188cc7dbcaf0cd56dd41d83cda216661fbe7))
+* **deps:** upgrade riffer to 0.49.0 ([#188](https://github.com/bottrall/riffer-rig/issues/188)) ([821413f](https://github.com/bottrall/riffer-rig/commit/821413f5af65bfcb159ddad532deb3c15779112d))
+* named prompt sections rendered every turn ([#184](https://github.com/bottrall/riffer-rig/issues/184)) ([d190a07](https://github.com/bottrall/riffer-rig/commit/d190a07dfa99764b82bba00745a07e7738c3532a))
+* provider setup table and typed auth.json credentials ([#185](https://github.com/bottrall/riffer-rig/issues/185)) ([0a30c35](https://github.com/bottrall/riffer-rig/commit/0a30c357793716acfabcd1ddd41ea9f98c8a6a8f))
+* store credentials on the Runtime ([#181](https://github.com/bottrall/riffer-rig/issues/181)) ([474a515](https://github.com/bottrall/riffer-rig/commit/474a51586011e413482f0275a7abd3a542e91914))
+
+
+### Code Refactoring
+
+* make the host contract the abstract Hosts::Base ([#183](https://github.com/bottrall/riffer-rig/issues/183)) ([3fd4f14](https://github.com/bottrall/riffer-rig/commit/3fd4f14a193d546ae06e00776f209a52c0593854))
+
 ## [0.5.0](https://github.com/bottrall/riffer-rig/compare/v0.4.0...v0.5.0) (2026-09-19)
 
 

data/README.md

@@ -26,19 +26,89 @@ 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 extension files; accepted now, with nothing to skip until they load   |
+| `--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 Anthropic. Provide your API key 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`.
+
+Each value resolves on its own: environment variable first, then the stored value, then a provider-specific fallback (the AWS shared config for the Bedrock region), then the prompt. Optional values are never prompted for.
+
+| Provider         | Environment variables                                                     | Guide                                              |
+| ---------------- | ------------------------------------------------------------------------- | -------------------------------------------------- |
+| `anthropic`      | `ANTHROPIC_API_KEY`                                                       | [Anthropic](docs/PROVIDERS.md#anthropic)           |
+| `openai`         | `OPENAI_API_KEY`; optional `OPENAI_BASE_URL`                              | [OpenAI](docs/PROVIDERS.md#openai)                 |
+| `gemini`         | `GEMINI_API_KEY`                                                          | [Gemini](docs/PROVIDERS.md#gemini)                 |
+| `openrouter`     | `OPENROUTER_API_KEY`                                                      | [OpenRouter](docs/PROVIDERS.md#openrouter)         |
+| `azure_openai`   | `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_KEY`                           | [Azure OpenAI](docs/PROVIDERS.md#azure-openai)     |
+| `amazon_bedrock` | `AWS_REGION` or `AWS_DEFAULT_REGION`; optional `AWS_BEARER_TOKEN_BEDROCK` | [Amazon Bedrock](docs/PROVIDERS.md#amazon-bedrock) |
+
+`auth.json` holds one typed entry per provider, and a stored secret may be a literal, a `$ENV_VAR` reference or a `!shell command` whose stdout is the secret:
+
+```json
+{
+  "anthropic": { "type": "api_key", "api_key": "sk-ant-…" },
+  "openai": { "type": "api_key", "api_key": "!security find-generic-password -s openai -w" }
+}
+```
+
+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.
 
-- Set the `ANTHROPIC_API_KEY` environment variable, or
-- Run `riffer` and paste your key when prompted on first launch. It is saved to `~/.riffer/auth.json` (file permissions `600`) for subsequent runs.
+### Switching the model
 
-Create a key at https://console.anthropic.com/settings/keys.
+`/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
 
-- `RIFFER_MODEL` — override the default model.
-- `AGENTS.md` — if present, an `AGENTS.md` in the current working directory and/or a global `~/.riffer/AGENTS.md` is loaded as additional context.
+- `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
+  {
+    "model": "anthropic/claude-sonnet-4-6",
+    "reasoning": "low",
+    "models": {
+      "anthropic/claude-sonnet-4-6": {
+        "input": 3.0,
+        "output": 15.0,
+        "cache_write": 3.75,
+        "cache_read": 0.3
+      }
+    }
+  }
+  ```
+
+  `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
 
@@ -62,7 +132,7 @@ PR titles are [conventional commits](https://www.conventionalcommits.org/) and a
 
 [release-please](https://github.com/googleapis/release-please) keeps a release PR open that bumps `lib/riffer/rig/version.rb` and writes `CHANGELOG.md`. Merging that PR tags `vX.Y.Z`, creates the GitHub Release and publishes the gem to RubyGems.org through Trusted Publishing; nothing is pushed by hand.
 
-riffer is pinned to one minor (`~> 0.45.0`) because its 0.x minors may break. When Dependabot opens the riffer bump, retitle it `feat(deps):` or `fix(deps):` before merging so it releases and appears in the changelog.
+riffer is pinned to one minor (`~> 0.49.0`) because its 0.x minors may break. When Dependabot opens the riffer bump, retitle it `feat(deps):` or `fix(deps):` before merging so it releases and appears in the changelog.
 
 ## Contributing
 

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,124 +1,92 @@
 # frozen_string_literal: true
 
-require 'io/console'
-
 module Riffer::Rig::CLI
   extend self
 
-  PROVIDER_URLS = {
-    'anthropic' => 'https://console.anthropic.com/settings/keys',
-    'openai' => 'https://platform.openai.com/api-keys',
-    'gemini' => 'https://aistudio.google.com/app/apikey',
-    'openrouter' => 'https://openrouter.ai/keys'
-  }.freeze #: Hash[String, String]
-
-  # @rbs output: IO
-  # @rbs input: IO
-  # @rbs return: Integer
-  def start(output: $stdout, input: $stdin)
-    theme = Riffer::Rig::UI::Theme.for(output)
-
-    model    = Riffer::Rig::Settings.model
-    provider = Riffer::Rig::Settings.provider_for(model)
-
-    api_key = (provider && Riffer::Rig::Credentials.api_key_for(provider)) || onboard(provider, theme, output:, input:)
-    return 1 if api_key.nil?
-
-    configure_provider(provider, api_key)
+  PRINT_FLAGS = %w[-p --print].freeze #: Array[String]
 
-    agent    = Riffer::Rig::CodingAgent.new
-    animator = Riffer::Rig::UI::Animator.new(io: output, theme:)
+  ACP_COMMAND = 'acp'
 
-    reveal_banner(theme, animator, model)
+  USAGE_ERROR = 2
 
-    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 api_key: String
-  # @rbs return: void
-  def configure_provider(provider, api_key)
-    case provider
-    when 'anthropic'  then Riffer.configure { |c| c.anthropic.api_key  = api_key }
-    when 'openai'     then Riffer.configure { |c| c.openai.api_key     = api_key }
-    when 'gemini'     then Riffer.configure { |c| c.gemini.api_key     = api_key }
-    when 'openrouter' then Riffer.configure { |c| c.openrouter.api_key = api_key }
-    end
-  end
-
-  # @rbs provider: String?
-  # @rbs theme: Riffer::Rig::UI::Theme
-  # @rbs output: IO
+  # @rbs flags: Riffer::Rig::CLI::Flags
   # @rbs input: IO
-  # @rbs return: String?
-  def onboard(provider, theme, output:, input:)
-    url  = (provider && PROVIDER_URLS[provider]) || 'your provider'
-    name = provider ? provider.capitalize : 'provider'
-
-    output.puts(theme.cyan('♪ welcome to riffer-rig ♪'))
-    output.puts(theme.grey("No #{name} API key found. Create one at #{url}"))
-    output.print("#{theme.pink('›')} Paste your #{name} API key #{theme.grey('(hidden)')}: ")
-
-    key = read_secret(input).to_s.strip
-    output.puts
-
-    if key.empty?
-      output.puts(theme.grey("No key entered. Set #{env_var_for(provider)} or re-run riffer to try again."))
-      return nil
+  # @rbs output: IO
+  # @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.save_api_key(provider, key) if provider
-    output.puts(theme.grey("Saved to #{Riffer::Rig::Credentials::PATH} (permissions 600)."))
-    key
-  end
-
-  # @rbs provider: String?
-  # @rbs return: String
-  def env_var_for(provider)
-    (provider && Riffer::Rig::Credentials::PROVIDER_ENV_VARS[provider]) || 'the appropriate API key env var'
   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