riffer-rig 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1743d133b2e91f50f10a376bbb8cd6f2d21f4d6c2f90600d5415d4ec9047b26
-  data.tar.gz: c8131bfda29574b5c86acb1b1ebebfe0ec1dc5cc82ff7c8c8cca5410bb7b34d0
+  metadata.gz: 9b1648704ba63c4826d30aec44988486557c4a2fccc5b3b527fef879fc407cef
+  data.tar.gz: 574c73fcb0f3512f486d6d4c355b69add66d54de82c87ed170c8409821c4b3f1
 SHA512:
-  metadata.gz: 46930dae154e4a07916c0f1391e3f44419a7e385f5d31f02509a9740276ca6bfc993efb4f0e95695ad439045f69d9c3a74e344a43af7f83a75afdb6bd94f1e58
-  data.tar.gz: 18ce4fe1003d1767a234936fae81fb921c49461cefb7f6516bf051047734b68580bfc124803d353296a71daa9919f5f77805c83bc3c2599c9e17e8b2650b4b1d
+  metadata.gz: 0da1408916c461365dc8d61c07dca3b00ad5f2d22d77e42d036d379ce6231c5cff0ae3ade79a2d8f907439c8e70e33753ae3e5b91786905e5366bf414d0f3521
+  data.tar.gz: 994802e5749d8708313eda67386af949ff4112b9b2275b6687a2078ea2f4332b8147916608cdbf8adb5f90c632bea9b395d5929b9024907f4811e2ecca75eff1

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.17.0](https://github.com/bottrall/riffer-rig/compare/v0.16.0...v0.17.0) (2026-10-24)
+
+
+### Features
+
+* authenticate to Anthropic through the SDK's credential chain ([#606](https://github.com/bottrall/riffer-rig/issues/606)) ([617fdb7](https://github.com/bottrall/riffer-rig/commit/617fdb76f5a54290d2d001b906fce3d530e2cef4))
+* give tools the background job registry as a documented context key ([#579](https://github.com/bottrall/riffer-rig/issues/579)) ([a8e98ac](https://github.com/bottrall/riffer-rig/commit/a8e98acef71b354a2c7601d46366ed0f95b6da37))
+
+
+### Bug Fixes
+
+* --save and /auth honour the injected home ([#596](https://github.com/bottrall/riffer-rig/issues/596)) ([032f26f](https://github.com/bottrall/riffer-rig/commit/032f26f317216f501a9dc71c3d1157ce12bc3893))
+* /auth and /model refusals say how to supply a missing credential ([#597](https://github.com/bottrall/riffer-rig/issues/597)) ([ffe18fe](https://github.com/bottrall/riffer-rig/commit/ffe18fe653db97f4bbb737359f454637bc347778))
+* reasoning in settings reaches the agent ([#577](https://github.com/bottrall/riffer-rig/issues/577)) ([9216429](https://github.com/bottrall/riffer-rig/commit/9216429421be51bb7511e4c8b6eec3bd177e8ba3))
+* reload each Loader-built runtime with its own build's choices ([#598](https://github.com/bottrall/riffer-rig/issues/598)) ([d6b95a6](https://github.com/bottrall/riffer-rig/commit/d6b95a6f1205ecb8ae0221c88bb1012c2ce15e79))
+* **terminal:** keep a capped input inside a short terminal ([#575](https://github.com/bottrall/riffer-rig/issues/575)) ([8b67c2b](https://github.com/bottrall/riffer-rig/commit/8b67c2b9d1ba404ffb12bb42f120e034aae8183b))
+
+## [0.16.0](https://github.com/bottrall/riffer-rig/compare/v0.15.0...v0.16.0) (2026-10-18)
+
+
+### Features
+
+* **terminal:** show the reasoning level in the banner and status bar ([#565](https://github.com/bottrall/riffer-rig/issues/565)) ([ead3588](https://github.com/bottrall/riffer-rig/commit/ead358834580a4fcab18432cbe5414e3e21b7feb))
+
 ## [0.15.0](https://github.com/bottrall/riffer-rig/compare/v0.14.0...v0.15.0) (2026-10-18)
 
 
@@ -15,6 +39,10 @@
 ## [0.14.0](https://github.com/bottrall/riffer-rig/compare/v0.13.0...v0.14.0) (2026-10-18)
 
 
+### Upgrading
+
+* the `models` pricing table in `settings.json` is no longer read. Move each entry into a [model catalog](https://riffer.ai/guides/catalog/) file's `pricing` — the same four rates, USD per million tokens — and list the file in `catalog_files`.
+
 ### Features
 
 * **headless:** print the session id on stderr ([#556](https://github.com/bottrall/riffer-rig/issues/556)) ([2816938](https://github.com/bottrall/riffer-rig/commit/2816938f66d32ccf557d83a33e40300e68a68032))

data/README.md

@@ -2,245 +2,66 @@
 
 **riffer, in your terminal and in your process.**
 
-`riffer-rig` is a general-purpose agent for Ruby developers who want to own their harness. It runs as a terminal agent and, because the runtime is separate from the terminal, it also runs inside any Ruby process: a Rails app, a script, a job. You extend it in Ruby: tools, commands, providers and hooks are ordinary Ruby classes on [riffer](https://github.com/janeapp/riffer)'s primitives, and the same objects work whether the host is the terminal or your app. It ships with a coding toolkit (read, write, edit, bash) as the default bundle, because a shell and file access are the most efficient way to get almost any task done — but the prompt gives it no coding identity. [Overview](docs/OVERVIEW.md) has the full thesis.
+`riffer-rig` is a general-purpose agent for Ruby developers who want to own their harness. It runs in your terminal, and because the runtime is separate from the terminal it also runs inside any Ruby process: a Rails app, a script, a job. You extend it in Ruby — tools, commands, providers and hooks are ordinary classes on [riffer](https://riffer.ai)'s primitives, and the same objects work in the terminal and in your app.
 
-## Requirements
+It ships with a coding toolkit (read, write, edit, bash) because a shell and file access get almost any task done, but nothing in its prompt makes it a coding agent. Tools run without asking for permission; see [what runs without asking](docs/TOOLS.md#what-runs-without-asking).
 
-- Ruby >= 4.0
+## Install
 
-## Installation
-
-Install the gem:
+Requires Ruby 4.0 or later.
 
 ```bash
 gem install riffer-rig
 ```
 
-This provides a `riffer` executable. No provider SDK is installed with it: `gemini/…` models work out of the box, and every other provider's SDK gem is either installed on its first use — `riffer-rig` asks, then installs it in-process — or added to a Gemfile ahead of time:
-
-```ruby
-gem 'anthropic', '~> 1.69'
-```
-
-[Providers](docs/PROVIDERS.md#sdk-gems) lists each provider's gem and how the install offer works.
-
-## Usage
-
-Run the agent from any project directory:
+## Quickstart
 
 ```bash
+cd my-project
 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)). The reasoning effort resolves the same way: `--reasoning`, `RIFFER_REASONING`, then `reasoning` in the settings ([Configuration](docs/CONFIGURATION.md#reasoning)).
-
-### Flags
-
-| Flag                    | Effect                                                                     |
-| ----------------------- | -------------------------------------------------------------------------- |
-| `--model provider/name` | the model for this session, over `RIFFER_MODEL` and the settings            |
-| `--reasoning LEVEL`     | the reasoning effort for this session, over `RIFFER_REASONING` 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                                          |
-| `--no-save`             | does not save this session to the [store](docs/SESSIONS.md)                 |
-| `-c`, `--continue`      | continues the most recent session in this directory ([Sessions](docs/SESSIONS.md#resuming)) |
-| `-r [ID]`, `--resume [ID]` | resumes the session with id `ID`; bare `-r` opens the [picker](docs/SESSIONS.md#the-picker) ([Sessions](docs/SESSIONS.md#resuming)) |
-| `-h`, `--help`          | prints the usage                                                            |
-| `-v`, `--version`       | prints the version                                                          |
-
-An editor registers the agent as `riffer acp`, the same Runtimes over the [Agent Client Protocol](https://agentclientprotocol.com) on stdio ([ACP](docs/ACP.md)).
-
-### Headless
-
-Run one prompt with no terminal ([Headless](docs/HEADLESS.md)):
-
-```bash
-riffer -p "what does this repo do"
-git diff | riffer -p "review this diff"   # piped stdin appended as context
-echo "explain this diff" | riffer -p      # piped stdin alone is the prompt
-```
-
-Everything loads exactly as the REPL does, the shared flags work the same — `-c` and `-r` included: `riffer -p -c "now run the tests"` continues the most recent session in this directory, and a missing session exits 2 ([Headless](docs/HEADLESS.md)). The session is saved like any other unless `--no-save`. Only the assistant's text is printed, streamed to stdout; errors and warnings go to stderr, and `--verbose` adds a one-line trace of each tool call there. With `--json`, stdout is instead one JSON object per line for every Runtime event — the NDJSON stream ([Headless](docs/HEADLESS.md#the-ndjson-stream---json)). A run whose model leaves background jobs running waits for them, giving the model a further turn as each one exits, and kills any left after `--job-idle-timeout` seconds (600 by default) without an exit ([Headless](docs/HEADLESS.md#background-jobs)). Headless never prompts: a missing model, credential, or SDK prints the reason on stderr and exits 2.
-
-The exit code says how the turn ended: `0` finished, `1` runtime error, `2` usage or configuration, `3` the turn ended without completing (`--max-steps`, a full context window, a provider content filter) or its background jobs passed the idle timeout, `130` SIGINT (the turn is cancelled first).
-
-### In the session
-
-Type a prompt and press Enter. While the turn runs, the status line under the input shows its time, steps, tool calls, tokens and cost, and Ctrl-T peeks at what the model is writing; the reply is printed when the turn ends, followed by a stat line (`N steps · mm:ss · ↑in · ↓out · session N tok`, plus the turn's cost and the session's when the model is [priced](docs/CONFIGURATION.md#catalog_files)). The input line stays open throughout: a message sent during a turn is queued and runs when the turn ends. [Terminal](docs/TERMINAL.md) has every key.
-
-- Ctrl-C during a turn cancels it. Ctrl-C with no turn running asks for a second one, which exits.
-- `/exit` or `/quit` ends the session, as does Ctrl-D on an empty line.
-- `/help` lists the session's slash commands. `/resume [--all]`, `/new`, `/cost`, `/trace`, `/skill:<name>` and the others are described in [Terminal](docs/TERMINAL.md#commands); `/model` is covered [below](#switching-the-model), and `/reasoning` works the same way for the reasoning effort.
-
-### Switching the model
-
-`/model provider/name` switches the model for the current session only, keeping the conversation so far, and confirms it in one line: `/model openai/gpt-5` prints `Model switched to openai/gpt-5`. 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. Switching runs the same setup for the new provider as startup does: its SDK gem is offered for install (or refused with the exact Gemfile line), and missing credentials are resolved — you are prompted for them when the host can ask, and the values apply to the running session immediately. The switch is refused with one error when the host cannot supply what is missing, and the model is left unchanged. `/model --save` writes the model in effect to the home `settings.json`, so new sessions start with it; `/model provider/name --save` switches and saves in one step, printing `Model switched to openai/gpt-5 and saved to ~/.riffer/settings.json` (a bare `/model --save` prints `Saved openai/gpt-5 to ~/.riffer/settings.json`), and a refused switch saves nothing ([Configuration](docs/CONFIGURATION.md#model)).
+The first run asks for a model as `provider/name` — for example `anthropic/claude-sonnet-4-6` — and then for that provider's API key, and saves both under `~/.riffer/`. `gemini/…` models work straight away; other providers' SDK gems are [offered for install](docs/PROVIDERS.md#sdk-gems) on first use.
 
-### Switching the reasoning level
+Type a prompt and press Enter. `/help` lists the commands, and [Getting started](docs/GETTING_STARTED.md) walks through a first session.
 
-`/reasoning level` switches the reasoning effort for the current session only, keeping the conversation so far: `/reasoning high` prints `Reasoning switched to high`, `/reasoning off` turns reasoning off, and `/reasoning` alone shows the level in effect. A level riffer does not accept is rejected naming the levels it accepts. `/reasoning --save` writes the level in effect to the home `settings.json` (`/reasoning high --save` switches and saves in one step), and a home file that no longer parses is reported instead of written. The switch survives a resume, and a `--reasoning` chosen for the run wins over it for that run only ([Configuration](docs/CONFIGURATION.md#reasoning)).
+## Extend it
 
-## Authentication
-
-`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.
-
-Inside a session, `/auth` lists every provider with where its secret comes from — `env`, `stored`, `chain` (the SDK's own credential chain, for Bedrock) or `missing`. `/auth <provider>` re-runs that provider's setup, which is how you rotate a key, and applies the new values to the current session, so the next request uses them. `/auth remove <provider>` deletes the provider's `auth.json` entry and its `providers` block in settings.
-
-## Configuration
-
-Settings live in two scopes, both optional: `~/.riffer/settings.json` for every project, and `<cwd>/.riffer/settings.json` for one project, merged key by key with the project winning ([Configuration](docs/CONFIGURATION.md)). Every core key is optional:
-
-| Key            | What it sets                                                                     |
-| -------------- | -------------------------------------------------------------------------------- |
-| `model`        | the model new sessions start with, as `provider/name`                            |
-| `reasoning`    | the reasoning effort, which riffer translates to the provider's own parameter    |
-| `catalog_files`| the model catalog JSON files holding pricing and reasoning maps                  |
-| `providers`    | non-secret provider fields such as an endpoint or region (home file only)        |
-| `extensions`   | `disabled` — bundled extensions to leave out; `autoload` — gem extension autoload |
-| `reload`       | `"auto"` (default) or `"manual"` — the hot-reload trigger                        |
-| `sessions`     | `save: false` stops saving sessions to the store                                 |
-| `tools`        | the provider-native tool switches (`native`), off by default                     |
-
-- `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_REASONING` — the reasoning effort for this run, winning over the `reasoning` setting; a level riffer does not accept is rejected naming the levels it accepts.
-- `AGENTS.md` — `~/.riffer/AGENTS.md` and an `AGENTS.md` in the current working directory or any directory above it 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 working directory up to the repository root, and in `~/.agents/skills/`, are offered to the model, and `/skill:<name> [text]` runs one ([Skills](docs/SKILLS.md)).
-- MCP servers — declared under the `mcp` key in either settings file and registered with the Runtime ([MCP](docs/MCP.md)).
-
-## Extending
-
-An extension is a named registrar block in a `rig.rb` file — `~/.riffer/rig.rb` runs in every project, `<project>/.riffer/rig.rb` in one, and the first run of a project file asks you to trust it:
+An extension is a Ruby block in `~/.riffer/rig.rb` (every project) or `.riffer/rig.rb` (one project):
 
 ```ruby
 Riffer::Rig.extension('git') do |rig|
-  # A tool the model can call
-  rig.tool GitLog
-
-  # A /log command in the session
-  rig.command('log', description: 'Recent commits') do |ctx|
-    ctx.say `git log --oneline -n #{ctx.args}`
-  end
-
-  # A section appended to the system message, re-read every turn
-  rig.prompt(:branch) { |ctx| "Branch: #{`git branch --show-current`}" }
+  rig.command('log', description: 'Recent commits') { |ctx| ctx.say `git log --oneline -n 10` }
+  rig.prompt(:branch) { "Current branch: #{`git branch --show-current`}" }
 end
 ```
 
-Tools, commands, prompt sections, event handlers, skills, MCP servers and providers register the same way, and the same objects work whether the host is the terminal or your app. [Extensions](docs/EXTENSIONS.md) has all eight seams, error isolation, and packaging an extension as a gem.
+That adds a `/log` command and puts the current branch in the system prompt on every turn. Extensions can also add tools, hooks, skills, MCP servers, settings and providers — [Extensions](docs/EXTENSIONS.md) starts with a complete tool.
 
-## Embedding
-
-The runtime is separate from the terminal, so the same agent runs inside any Ruby process:
+## Embed it
 
 ```ruby
 runtime = Riffer::Rig::Loader.runtime(cwd: Dir.pwd, host: Riffer::Rig::Hosts::Null.new)
-response = runtime.ask('why is this test failing?')
-puts response.content
+puts runtime.ask('why is this test failing?').content
 ```
 
-`Loader.runtime` applies the same filesystem conventions as the terminal — settings, credentials, `rig.rb`, skills. [Embedding](docs/EMBEDDING.md) has the streaming `prompt`, snapshots, and rebuilding after a code reload.
+This builds the same agent the terminal does, from the same settings, credentials and extensions. [Embedding](docs/EMBEDDING.md) covers streaming, cancelling, snapshots and reloading.
 
 ## Documentation
 
-The guides, in reading order:
-
-Start here:
-
-- [Overview](https://riffer.bottrall.dev/guides/overview/) — What riffer-rig is, the four tiers, the runtime and host layers
-- [Getting started](https://riffer.bottrall.dev/guides/getting-started/) — Install, pick a model, first session
-
-Using the terminal:
-
-- [Terminal](https://riffer.bottrall.dev/guides/terminal/) — The input line and its keys, queueing, the status line, peek, resume replay
-- [Configuration](https://riffer.bottrall.dev/guides/configuration/) — Settings scopes and every core key
-- [Instructions](https://riffer.bottrall.dev/guides/instructions/) — How the system message is built; AGENTS.md
-- [Tools](https://riffer.bottrall.dev/guides/tools/) — The bundled toolkit and provider-native tools
-- [Skills](https://riffer.bottrall.dev/guides/skills/) — Agent Skills directories and activation
-- [MCP](https://riffer.bottrall.dev/guides/mcp/) — Declaring MCP servers
-- [Sessions](https://riffer.bottrall.dev/guides/sessions/) — Saving, resuming, the picker, the JSONL store
-- [Reloading](https://riffer.bottrall.dev/guides/reloading/) — The /reload command, what reloads and what does not
-- [Headless](https://riffer.bottrall.dev/guides/headless/) — riffer -p, NDJSON, exit codes
-- [ACP](https://riffer.bottrall.dev/guides/acp/) — riffer acp, the ACP agent over stdio
+The guides are at **<https://riffer.bottrall.dev>**, and their sources are in [`docs/`](docs/). Good places to start:
 
-Extending and embedding:
-
-- [Extensions](https://riffer.bottrall.dev/guides/extensions/) — rig.rb, the registrar, the eight seams, commands, handlers, gems
-- [Embedding](https://riffer.bottrall.dev/guides/embedding/) — Runtime and Loader from Ruby; snapshots; rebuild
-- [Hosts](https://riffer.bottrall.dev/guides/hosts/) — The Host interface and writing a host
-
-Providers:
-
-- [Providers](https://riffer.bottrall.dev/guides/providers/overview/) — Model strings, precedence, credentials, /auth
-- [Custom providers](https://riffer.bottrall.dev/guides/providers/custom/) — Registering a provider from an extension; the setup, credentials, listings
-
-The guide sources are in `docs/`. To preview the site locally, run `bin/docs serve` and open <http://localhost:8000>.
-
-## Development
-
-Every project chore is a script in `bin/`. The Rakefile behind them is an implementation detail; you never need to call rake directly.
-
-| Script          | What it does                                                                                   |
-| --------------- | ---------------------------------------------------------------------------------------------- |
-| `bin/setup`     | Install dependencies on a fresh checkout (gems + rbs collection)                               |
-| `bin/test`      | Run the test suite. Pass files and/or Minitest flags: `bin/test test/foo_test.rb -n /pattern/` |
-| `bin/lint`      | Run RuboCop. Arguments are forwarded, e.g. `bin/lint -a`                                       |
-| `bin/typecheck` | Check the rbs collection lockfile and `sig/generated` are current, then type-check with Steep  |
-| `bin/rbs`       | Regenerate `sig/generated` from the inline annotations in `lib/`                               |
-| `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 |
-
-## Releasing
-
-PR titles are [conventional commits](https://www.conventionalcommits.org/) and are linted in CI: `feat:` bumps the minor version, `fix:` bumps the patch, and `feat!:` marks a breaking change (also a minor bump while we are on 0.x). `chore:`, `docs:`, `ci:`, `refactor:` and `test:` never release. Squash-merging makes the title the commit on `main`.
-
-A PR whose code nothing in the live path reaches yet is titled `refactor:`, including fixes to such code; the PR that wires it in carries the `feat:` or `fix:`, titled for what the user gets. The changelog and GitHub Release are generated from titles, so a `feat:` on unreachable code advertises a feature nobody can use.
-
-[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.
+- [Overview](docs/OVERVIEW.md) — what riffer-rig is and how it fits together
+- [Configuration](docs/CONFIGURATION.md) — settings and where each value comes from
+- [Command line](docs/CLI.md) — every flag
+- [Headless mode](docs/HEADLESS.md) — one prompt from a script or CI job, with exit codes and an NDJSON stream
+- [ACP](docs/ACP.md) — riffer-rig in your editor, with `riffer acp`
+- [Extensions](docs/EXTENSIONS.md) — your own tools, commands and hooks
 
 ## Contributing
 
-1. Fork the repository and create your branch: `git checkout -b feature/foo`
-2. Run the tests and linters locally.
-3. Submit a pull request with a clear description of the change.
-
-Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+[`AGENTS.md`](AGENTS.md) has the scripts and the project's conventions. Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License
 
-Licensed under the MIT License. See [`LICENSE.txt`](LICENSE.txt) for details.
-
-## Maintainer
-
-- Jake Bottrall - https://github.com/bottrall
+MIT — see [`LICENSE.txt`](LICENSE.txt). Maintained by [Jake Bottrall](https://github.com/bottrall).

data/lib/riffer/rig/acp/mapper.rb

@@ -27,6 +27,18 @@ module Riffer::Rig::ACP::Mapper
     blocks.filter_map { |block| prompt_text_of(block) }.join("\n\n")
   end
 
+  # @rbs event: ::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event
+  # @rbs return: ::ACP::Types::SessionUpdate::t?
+  def update_for(event)
+    case event
+    when Riffer::StreamEvents::TextDelta then message_chunk(event.content)
+    when Riffer::Rig::Events::CommandOutput then message_chunk(event.text)
+    when Riffer::StreamEvents::ToolCallDone then tool_call(event)
+    when Riffer::Rig::Events::AfterToolCall then tool_call_done(event)
+    when Riffer::Rig::Events::JobExit then job_exit
+    end
+  end
+
   # @rbs content: String
   # @rbs return: ::ACP::Types::SessionUpdate::AgentMessageChunk
   def message_chunk(content)
@@ -96,10 +108,10 @@ module Riffer::Rig::ACP::Mapper
   def stop_reason_of(stop_reason)
     case stop_reason
     when :completed then ::ACP::Types::StopReason::END_TURN
-    when Riffer::Rig::Runtime::INTERRUPT_CANCELLED then ::ACP::Types::StopReason::CANCELLED
+    when Riffer::Rig::Runtime::StopReason::INTERRUPT_CANCELLED then ::ACP::Types::StopReason::CANCELLED
     when :max_steps then ::ACP::Types::StopReason::MAX_TURN_REQUESTS
     else
-      stopped = Riffer::Rig::Runtime::STOPPED_WITHOUT_COMPLETING.include?(stop_reason)
+      stopped = Riffer::Rig::Runtime::StopReason::STOPPED_WITHOUT_COMPLETING.include?(stop_reason)
       stopped ? ::ACP::Types::StopReason::MAX_TOKENS : ::ACP::Types::StopReason::REFUSAL
     end
   end

data/lib/riffer/rig/acp/servers.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Riffer::Rig::ACP::Servers
+  extend self
+
+  # @rbs servers: Array[::ACP::Types::McpServer::t]
+  # @rbs return: Hash[String, Riffer::Rig::Mcp::Declaration]
+  def declarations(servers)
+    servers.filter_map { |server| declaration_of(server) }.to_h
+  end
+
+  # @rbs servers: Array[::ACP::Types::McpServer::t]
+  # @rbs return: Array[String]
+  def warnings(servers)
+    servers.filter_map do |server|
+      next if server.is_a?(::ACP::Types::McpServerStdio)
+
+      "Skipped MCP server #{name_of(server)}: only stdio servers are supported"
+    end
+  end
+
+  private
+
+  # @rbs server: ::ACP::Types::McpServer::t
+  # @rbs return: [String, Riffer::Rig::Mcp::Declaration]?
+  def declaration_of(server)
+    return unless server.is_a?(::ACP::Types::McpServerStdio)
+
+    [
+      server.name,
+      Riffer::Rig::Mcp::Declaration.new(
+        command: server.command, args: server.args, env: server.env.to_h { |variable| [variable.name, variable.value] }
+      )
+    ]
+  end
+
+  # @rbs server: ::ACP::Types::McpServer::t
+  # @rbs return: String
+  def name_of(server)
+    server.is_a?(Hash) ? server['name'].to_s : server.name
+  end
+end

data/lib/riffer/rig/acp.rb

@@ -36,10 +36,6 @@ class Riffer::Rig::ACP
     new(input: input, output: output, env: env, home: home, cwd: cwd, build: build, adopt: adopt)
   end
 
-  # Builds the Runtime a session runs on: the client's MCP servers flow
-  # through the rig.mcp seam as a synthetic extension, so a reload rebuild
-  # re-declares them and a same-name declaration from an extension replaces
-  # them with the usual notify.
   # @rbs cwd: String
   # @rbs host: Riffer::Rig::Hosts::_Host
   # @rbs servers: Hash[String, Riffer::Rig::Mcp::Declaration]
@@ -57,6 +53,8 @@ class Riffer::Rig::ACP
   def self.session_extensions(servers)
     return [] if servers.empty?
 
+    # A synthetic extension, so a reload rebuild re-declares the servers and an
+    # extension's same-name declaration replaces them with the usual notify.
     extension = Riffer::Rig::Extension.new(SESSION_EXTENSION) do |rig|
       servers.each { |name, server| rig.mcp(name, command: server.command, args: server.args, env: server.env) }
     end
@@ -88,8 +86,6 @@ class Riffer::Rig::ACP
     @lock = Mutex.new
   end
 
-  # Serves the connection until the client closes stdin; then the reader
-  # thread ends and run returns.
   # @rbs &block: ? (::ACP::AgentConnection) -> void
   # @rbs return: Integer
   def run
@@ -129,7 +125,7 @@ class Riffer::Rig::ACP
     end
     ::ACP::Types::NewSessionResponse.new(session_id: runtime.id)
   rescue StandardError => e
-    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: e.message)
+    internal_error(e)
   end
 
   # @rbs request: ::ACP::Types::PromptRequest
@@ -143,19 +139,10 @@ class Riffer::Rig::ACP
     stop_reason = :completed
     dispatch(runtime, Riffer::Rig::ACP::Mapper.prompt_text(request.prompt)) do |event|
       case event
-      when Riffer::StreamEvents::TextDelta
-        client.update(request.session_id, Riffer::Rig::ACP::Mapper.message_chunk(event.content))
-      when Riffer::Rig::Events::CommandOutput
-        client.update(request.session_id, Riffer::Rig::ACP::Mapper.message_chunk(event.text))
-      when Riffer::StreamEvents::ToolCallDone
-        client.update(request.session_id, Riffer::Rig::ACP::Mapper.tool_call(event))
-      when Riffer::Rig::Events::AfterToolCall
-        client.update(request.session_id, Riffer::Rig::ACP::Mapper.tool_call_done(event))
-      when Riffer::Rig::Events::JobExit
-        client.update(request.session_id, Riffer::Rig::ACP::Mapper.job_exit)
-      when Riffer::Rig::Events::TurnEnd
-        stop_reason = event.stop_reason
+      when Riffer::Rig::Events::TurnEnd then stop_reason = event.stop_reason
       end
+      update = Riffer::Rig::ACP::Mapper.update_for(event)
+      client.update(request.session_id, update) if update
     end
     # A reload in the dispatch, by /reload or the automatic check, can change
     # the commands; its rebuild also reorders them, which is no change.
@@ -168,9 +155,7 @@ class Riffer::Rig::ACP
       message: 'a prompt is already running on this session; wait for it to finish or cancel it'
     )
   rescue StandardError => e
-    ::ACP::RequestError.new(
-      code: ::ACP::RequestError::INTERNAL_ERROR, message: Riffer::Rig::Runtime::ErrorMessage.of(e)
-    )
+    internal_error(e)
   end
 
   # @rbs request: ::ACP::Types::LoadSessionRequest
@@ -192,7 +177,7 @@ class Riffer::Rig::ACP
     client.available_commands(request.session_id, available_commands(runtime))
     ::ACP::Types::LoadSessionResponse.new
   rescue StandardError => e
-    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: e.message)
+    internal_error(e)
   end
 
   # @rbs request: ::ACP::Types::ListSessionsRequest
@@ -215,7 +200,7 @@ class Riffer::Rig::ACP
     end
     ::ACP::Types::ListSessionsResponse.new(sessions: sessions)
   rescue StandardError => e
-    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: e.message)
+    internal_error(e)
   end
 
   # Runs on the transport's reader thread, so it asks the turn to stop and
@@ -255,6 +240,12 @@ class Riffer::Rig::ACP
     @lock.synchronize { @sessions[id] }
   end
 
+  # @rbs error: StandardError
+  # @rbs return: ::ACP::RequestError
+  def internal_error(error)
+    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: Riffer::Rig::Runtime::ErrorMessage.of(error))
+  end
+
   # @rbs runtime: Riffer::Rig::Runtime
   # @rbs text: String
   # @rbs &: (::Riffer::StreamEvents::Base | Riffer::Rig::Events::_Event) -> void
@@ -312,38 +303,8 @@ class Riffer::Rig::ACP
   # @rbs host: Riffer::Rig::ACP::Host
   # @rbs return: Hash[String, Riffer::Rig::Mcp::Declaration]
   def declarations(servers, host)
-    servers.filter_map { |server| declaration_of(server, host) }.to_h
-  end
-
-  # @rbs server: ::ACP::Types::McpServer::t
-  # @rbs host: Riffer::Rig::ACP::Host
-  # @rbs return: [String, Riffer::Rig::Mcp::Declaration]?
-  def declaration_of(server, host)
-    unless server.is_a?(::ACP::Types::McpServerStdio)
-      host.notify("Skipped MCP server #{server_name(server)}: only stdio servers are supported", level: :warning)
-      return nil
-    end
-
-    [
-      server.name,
-      Riffer::Rig::Mcp::Declaration.new(command: server.command, args: server.args, env: stdio_env(server))
-    ]
-  end
-
-  # @rbs server: ::ACP::Types::McpServer::t
-  # @rbs return: String
-  def server_name(server)
-    case server
-    when ::ACP::Types::McpServer::Http, ::ACP::Types::McpServer::Sse then server.name
-    when Hash then server['name'].to_s
-    else 'unnamed'
-    end
-  end
-
-  # @rbs server: ::ACP::Types::McpServerStdio
-  # @rbs return: Hash[String, String]
-  def stdio_env(server)
-    server.env.to_h { |variable| [variable.name, variable.value] }
+    Riffer::Rig::ACP::Servers.warnings(servers).each { |warning| host.notify(warning, level: :warning) }
+    Riffer::Rig::ACP::Servers.declarations(servers)
   end
 
   # @rbs runtime: Riffer::Rig::Runtime

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

@@ -9,6 +9,8 @@ class Riffer::Rig::CLI::Flags
            riffer acp           serve Runtimes as an ACP agent over stdio
   TEXT
 
+  HEADLESS_ONLY = %i[verbose json job-idle-timeout].freeze #: Array[Symbol]
+
   # @dynamic model, reasoning, extensions, skills, agents_md, tools, max_steps, help, version
   # @dynamic save, verbose, json, job_idle_timeout, headless, prompt, continue, resume
   attr_reader :model #: String?
@@ -34,6 +36,9 @@ class Riffer::Rig::CLI::Flags
     return "invalid argument: --max-steps #{flags.max_steps}" if flags.max_steps&.<(1)
     return "invalid argument: --job-idle-timeout #{flags.job_idle_timeout}" if flags.job_idle_timeout&.negative?
 
+    stray = HEADLESS_ONLY.find { |key| values.key?(key) } unless flags.headless || flags.help || flags.version
+    return "--#{stray} is only available with -p" if stray
+
     flags
   rescue OptionParser::ParseError => e
     e.message

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

@@ -3,9 +3,6 @@
 class Riffer::Rig::CLI::Sessions
   OFF = 'Sessions are off for this run (--no-save).' #: String
 
-  # The terminal's sessions collaborator: translates the parsed flags into
-  # Loader builds and store lookups, so the host never sees the flags.
-  #
   # @rbs @flags: Riffer::Rig::CLI::Flags
   # @rbs @env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
   # @rbs @cwd: String

data/lib/riffer/rig/cli.rb

@@ -31,9 +31,6 @@ module Riffer::Rig::CLI
     return refuse(flags, error) if flags.is_a?(String)
     return help(output) if flags.help
     return version(output) if flags.version
-    return refuse('--verbose is only available with -p', error) if flags.verbose && !flags.headless
-    return refuse('--json is only available with -p', error) if flags.json && !flags.headless
-    return refuse('--job-idle-timeout is only available with -p', error) if flags.job_idle_timeout && !flags.headless
 
     return headless(flags, input:, output:, error:, env:, cwd:, home:) if flags.headless