Make Pi the default agent provider

README.md

@@ -9,7 +9,7 @@ A Ruby-based domain-specific language for creating structured AI workflows. Buil
 Roast lets you orchestrate AI workflows by combining "cogs" - building blocks that interact with LLMs, run code, execute commands, and process data. Write workflows that:
 
 - **Chain AI steps together** - Output from one cog flows seamlessly to the next
-- **Run coding agents locally** - Full filesystem access with Claude Code or other providers
+- **Run coding agents locally** - Full filesystem access with Pi, Claude Code, or other providers
 - **Process collections** - Map operations over arrays with serial or parallel execution
 - **Control flow intelligently** - Conditional execution, iteration, and error handling
 - **Reuse workflow components** - Create modular, parameterized scopes
@@ -48,7 +48,7 @@ bin/roast execute analyze_codebase.rb
 ## Core Cogs
 
 - **`chat`** - Send prompts to cloud-based LLMs (OpenAI, Anthropic, Perplexity & Gemini)
-- **`agent`** - Run local coding agents with filesystem access (Claude Code CLI, etc.)
+- **`agent`** - Run local coding agents with filesystem access (Pi CLI, Claude Code CLI, etc.)
 - **`ruby`** - Execute custom Ruby code within workflows
 - **`cmd`** - Run shell commands and capture output
 - **`map`** - Process collections in serial or parallel
@@ -70,7 +70,7 @@ gem 'roast-ai'
 
 - Ruby 3.0+
 - API keys or local credentials for your AI provider
-- Claude Code CLI installed (for the default agent provider)
+- Pi CLI installed (for the default agent provider)
 
 ## Provider Configuration
 
@@ -97,7 +97,7 @@ end
 
 ### Agent cog
 
-The `agent` cog runs local agent CLIs. It defaults to `:claude` and currently supports:
+The `agent` cog runs local agent CLIs. It defaults to `:pi` and currently supports:
 
 - `:claude` - Claude Code CLI
 - `:pi` - Pi CLI
@@ -123,7 +123,7 @@ Roast currently supports four LLM providers for the `chat` cog: **OpenAI**, **An
 
 The default model is set per-provider and can only be overridden inside a `config` block. See the [tutorial](https://github.com/Shopify/roast/blob/main/tutorial/01_your_first_workflow/README.md#adding-configuration) for examples.
 
-The `agent` cog is powered by the Claude Code CLI by default, which handles its own authentication.
+The `agent` cog is powered by the Pi CLI by default, which handles its own authentication.
 
 ## Getting Started
 

internal/documentation/comments/doc-comments-external.md

@@ -165,7 +165,7 @@ shortened names can be confusing. Use the complete module path.
 ```ruby
 # Configure the cog to use the default provider when invoking an agent
 #
-# The default provider used by Roast is Anthropic Claude Code (`:claude`).
+# The default provider used by Roast is Pi (`:pi`).
 #: () -> void
 def use_default_provider!
   @values[:provider] = nil
@@ -386,7 +386,7 @@ end
 # Configure the cog to use a specified provider when invoking an agent
 #
 # The provider is the source of the agent tool itself.
-# If no provider is specified, Anthropic Claude Code (`:claude`) will be used as the default provider.
+# If no provider is specified, Pi (`:pi`) will be used as the default provider.
 #
 # A provider must be properly installed on your system in order for Roast to be able to use it.
 #
@@ -519,7 +519,7 @@ Methods in `config_context.rbi` expose cog configuration interfaces and are the
 #
 # #### Configure the LLM provider
 # - `provider(symbol)` - Set the agent provider (e.g., `:claude`)
-# - `use_default_provider!` - Use the default provider (`:claude`)
+# - `use_default_provider!` - Use the default provider (`:pi`)
 #
 # #### Configure the base command used to run the coding agent
 # - `command(string_or_array)` - Set the base command for invoking the agent

internal/documentation/comments/doc-comments.md

@@ -70,7 +70,7 @@ These files provide the primary interface between users and Roast. The documenta
 # Configure the cog to use a specified provider when invoking an agent
 #
 # The provider is the source of the agent tool itself.
-# If no provider is specified, Anthropic Claude Code (`:claude`) will be used as the default provider.
+# If no provider is specified, Pi (`:pi`) will be used as the default provider.
 #
 # A provider must be properly installed on your system in order for Roast to be able to use it.
 #

lib/roast/cogs/agent/config.rb

@@ -5,12 +5,12 @@ module Roast
   module Cogs
     class Agent < Cog
       class Config < Cog::Config
-        VALID_PROVIDERS = [:claude, :pi].freeze #: Array[Symbol]
+        VALID_PROVIDERS = [:pi, :claude].freeze #: Array[Symbol]
 
         # Configure the cog to use a specified provider when invoking an agent
         #
         # The provider is the source of the agent tool itself.
-        # If no provider is specified, Anthropic Claude Code (`:claude`) will be used as the default provider.
+        # If no provider is specified, Pi (`:pi`) will be used as the default provider.
         #
         # A provider must be properly installed on your system in order for Roast to be able to use it.
         #
@@ -24,7 +24,7 @@ def provider(provider)
 
         # Configure the cog to use the default provider when invoking an agent
         #
-        # The default provider used by Roast is Anthropic Claude Code (`:claude`).
+        # The default provider used by Roast is Pi (`:pi`).
         #
         # The provider must be properly installed on your system in order for Roast to be able to use it.
         #

sorbet/rbi/shims/lib/roast/config_context.rbi

@@ -141,7 +141,7 @@ module Roast
     #
     # #### Configure the agent provider
     # - `provider(symbol)` - Set the agent provider (e.g., `:claude`)
-    # - `use_default_provider!` - Use the default provider (`:claude`)
+    # - `use_default_provider!` - Use the default provider (`:pi`)
     #
     # #### Configure the base command used to run the coding agent
     # - `command(string_or_array)` - Set the base command for invoking the agent

tutorial/02_chaining_cogs/README.md

@@ -127,8 +127,36 @@ execute do
 end
 ```
 
-The `agent` cog is backed by a locally installed coding agent -- Anthropic's Claude Code is the default provider.
-You'll need to have Claude Code installed and configured correctly for this cog to run.
+The `agent` cog is backed by a locally installed coding agent -- Pi is the default provider.
+You'll need to have Pi installed and configured correctly for this cog to run.
+
+### Specifying a Model
+
+Model names for the `agent` cog depend on the provider:
+
+- **Pi** (the default) needs a fully-qualified `provider/model` id:
+
+```ruby
+config do
+  agent do
+    model "anthropic/claude-haiku-4-5-20251001"
+  end
+end
+```
+
+- **Claude Code** (`provider :claude`) takes the bare model name -- just drop the `anthropic/` prefix:
+
+```ruby
+config do
+  agent do
+    provider :claude
+    model "claude-haiku-4-5-20251001"
+  end
+end
+```
+
+A bare name like `"claude-haiku-4-5-20251001"` (or a shorthand like `"haiku"`) **only** works when you've set
+`provider :claude`. On the default Pi provider it will fail, because Pi can't resolve an unqualified model name.
 
 ### When to Use Agent vs Chat
 

tutorial/02_chaining_cogs/code_review.rb

@@ -8,8 +8,8 @@
 
 config do
   agent do
-    model "claude-haiku-4-5-20251001"
-    provider :claude
+    model "anthropic/claude-haiku-4-5-20251001"
+    provider :pi
   end
 
   chat do

tutorial/02_chaining_cogs/session_resumption.rb

@@ -13,6 +13,7 @@
     model "gpt-5.4-nano"
   end
   agent do
+    provider :claude
     model "haiku"
     no_display!
     show_stats!

tutorial/README.md

@@ -15,7 +15,7 @@ run coding agents, process data, and so much more.
 - Ruby installed (3.4.2+)
 - Roast gem installed
 - API keys for your AI provider (see [Configuration](https://github.com/Shopify/roast/blob/main/README.md#configuration) for setup)
-- Claude Code CLI installed and configured (to use coding agents)
+- Pi CLI installed and configured for default agent examples; Claude Code CLI installed and configured for examples that set `provider :claude`
 
 ## How to Use This Tutorial