silas 0.4.0 → 0.6.0

data/docs/vs-eve.md

@@ -0,0 +1,93 @@
+# Silas vs eve
+
+> Written **2026-07-26** against **eve 0.27.6** and Silas 0.5.x, from eve's
+> published docs and source. Both projects move fast — if you're reading this
+> much later, re-verify before deciding.
+
+Silas and eve share the same organising idea: **an agent is a directory of
+conventional files** — instructions, one file per tool, skills, schedules,
+channels, connections — running on a durable loop. You can build the same
+things with either: support desks, scheduled analysts, Slack copilots,
+back-office automations. eve is TypeScript-native, built by Vercel on the AI
+SDK, and fully self-hostable. Silas is Rails-native, a gem inside your
+existing app.
+
+So the honest first cut is simply your stack: **a TypeScript team should use
+eve; a Rails team should use Silas.** The rest of this page is for people near
+the boundary — and for the differences that go deeper than language.
+
+---
+
+## The comparison
+
+| | Silas | eve (0.27.6) |
+|---|---|---|
+| **Shape** | A gem in your Rails app — your database, your job queue, your auth, one deploy. | A TypeScript service beside your app, with its own workflow store and deploy. |
+| **Authoring** | A directory of plain files. | A directory of plain files — genuinely the same idea. |
+| **Durable loop** | Survives `kill -9`, resumes from the last completed step. Chaos-gated every release: zero duplicate effects, byte-identical replay, SQLite + Postgres. | Workflow-engine replay; interrupted steps re-run. |
+| **Tool-effect semantics** | **Exactly-once** for DB-recorded effects (`transactional!` — effect + ledger in one transaction). Default at-most-once: an ambiguous crash **parks for a human**. | **At-least-once, documented as such** — "make non-idempotent side effects like charges or emails idempotent, or gate them with approval." Dedup is the tool author's job. |
+| **Human-in-the-loop** | Parks at zero compute; cleared from inbox, Slack, signed email, or API; parks expire; `ask_question` for the reverse direction. | `needsApproval` on tools. |
+| **Operator surface** | A production inbox mounted in your app: live traces, approval cards, audit trail, cost accounting, web chat. | A dev TUI ("not a production chat UI or customer-facing dashboard"); production UIs are assembled from templates. |
+| **Memory** | Shipped: approval-gated triples with provenance and supersession. | Deliberately out of scope. |
+| **Ecosystem** | Ruby/Rails. | TypeScript + the AI SDK — a much larger ecosystem, with Vercel's distribution behind it. |
+| **Channels & integrations** | Slack + email built in; a generator scaffolds any transport. | More first-party surfaces, growing quickly. |
+| **Maturity** | Early (0.5.x); the durability contract is chaos-verified on every release. | Weeks old publicly; backed by a platform company, shipping at platform speed. |
+
+---
+
+## Where Silas goes further
+
+**The transaction boundary.** When an agent's consequential action is a row in
+your own database — a refund, a balance move, a ledger entry — Silas commits
+the effect and the ledger's dedup record **in the same transaction**. Crash
+before commit: both roll back. Crash after: the step is skipped on resume.
+No idempotency keys, no reconciliation. This isn't about hosting — it's about
+*whose transaction it is*: any runtime outside your application database,
+self-hosted or not, keeps its "this step ran" record in its own store, and two
+stores can't commit atomically. eve's docs draw the same conclusion from the
+other side: make your side effects idempotent, or gate them. Silas is the
+framework where you don't have to.
+
+**Ambiguity parks.** At-least-once means a crash can re-fire a side effect.
+Silas's default is at-most-once with **in-doubt → human**: it never
+double-fires, and an ambiguous call waits for a person.
+
+**The operator surface ships.** `mount Silas::Engine` and the inbox exists —
+held/working/filed rail, live traces, approval cards, audit trail, cost, web
+chat — behind your app's own auth.
+
+**Memory ships.** Approval-gated, with provenance and supersession. eve
+reasonably says "bring your own"; Silas ships the batteries.
+
+## Where eve goes further
+
+- **The ecosystem.** TypeScript and the AI SDK are where most of the agent
+  world lives — more examples, more integrations, a bigger hiring pool, and
+  Vercel's reach.
+- **Surface breadth and velocity.** More first-party channels and
+  integrations today, with a platform company's release cadence.
+- **Sandboxing posture.** Container sandboxes are integral to eve's design.
+  Silas ships an interim Docker seam and reaches microVM-class isolation via
+  the [hermetic](https://github.com/danielstpaul/hermetic) gem.
+
+---
+
+## Choosing
+
+**Pick Silas** if you're on Rails — your agent's tools are ordinary Ruby
+against your own models, the inbox lives behind your auth, and effects your
+app records in its own database get exactly-once semantics no external
+runtime can match. Especially if your agents move money.
+
+**Pick eve** if you're in TypeScript — it's an excellent framework with the
+same authoring model, the ecosystem's momentum, and Vercel behind it.
+
+Near the boundary (a Rails shop with a TS front-of-house, say): decide by
+where your consequential side effects live. If they're rows in the Rails
+app's database, that's where the agent belongs.
+
+---
+
+*Claims about eve come from its docs and source at 0.27.6, quoted or
+paraphrased in good faith; corrections welcome. Silas's numbers are
+reproducible from `chaos_host/results/`.*

data/docs/why-silas.md

@@ -0,0 +1,87 @@
+# Why Silas
+
+## Build agents the way you build Rails apps
+
+Silas is for the same things every modern agent framework is for: a support
+desk that actually resolves tickets, an analyst that posts the Monday digest,
+an ops copilot in Slack, a back-office agent that chases invoices. An agent is
+a directory of plain files — a persona, a data-only config, one file per tool
+— and the framework supplies the durable loop, the scheduling, the channels,
+the memory, and the operator surface. If you've looked at eve, the authoring
+model will feel immediately familiar; that shape is the category's best idea,
+and Silas embraces it.
+
+What's different is *where it runs*. Silas isn't a second runtime you stand
+beside your app — it's a gem inside the Rails app you already deploy:
+
+- **Your tools are your app.** `Order.find_by!`, `refunds.create!`, your
+  service objects, your validations — no RPC layer between the agent and the
+  domain, because the agent lives where the domain lives.
+- **Your auth is the agent's auth.** The operator inbox mounts as an engine
+  and hides behind whatever `current_user` already means. No second dashboard,
+  no second login, no second audit domain.
+- **Your deploy is the agent's deploy.** One repo, one CI, one Kamal push.
+  The durable substrate — a database, Solid Queue, Active Job Continuations —
+  is already booted.
+
+## The guarantees go further
+
+Every serious framework makes the loop durable. Silas draws the line a step
+past that, and verifies it with a chaos harness that `kill -9`s live agents
+hundreds of times per release (zero duplicate effects, byte-identical replay
+— [guarantees](guarantees.md)):
+
+- **Exactly-once tool effects.** A `transactional!` tool's database write and
+  the ledger's record of it commit in **one transaction**. A crash mid-refund
+  leaves exactly one refund row — never two, never zero — with no idempotency
+  key required. Only a framework *inside* your app can offer this: an external
+  runtime's ledger can never join your database transaction.
+- **Ambiguity waits for a person.** The default mode is at-most-once: a crash
+  that makes "did it send?" unanswerable parks the call **in doubt** for a
+  human verdict instead of re-firing blind. Never double-pay; sometimes ask.
+- **Holds cost nothing.** An approval, a question, or a budget breach parks
+  the turn at zero compute — the job exits, and clearing it resumes from
+  durable rows without re-calling the model.
+
+If your agents only ever read, any durable loop will do. The moment one
+touches money, inventory, or anything you'd hate to see happen twice, this is
+the difference you'll feel.
+
+## Batteries included
+
+A production operator inbox (live traces, approval cards, audit trail, cost
+accounting), approval-gated memory with provenance, deterministic evals as a
+deploy gate, Slack and email channels plus a generator for any transport, a
+JSON API with SSE, per-turn budgets, replay-safe compaction — shipped in the
+gem, not assembled from templates. And one command builds a working agent app
+from nothing:
+
+```bash
+rails new desk -m https://raw.githubusercontent.com/danielstpaul/silas/main/templates/desk.rb
+```
+
+## The honest notes
+
+- **Silas is early** — 0.5.x, and the guarantees are proven by a reproducible
+  chaos harness rather than years of production traffic. The contract is
+  measured on every release, and it's stated precisely so you know exactly
+  what's promised.
+- **Rails-only, on purpose.** If your team lives in TypeScript, eve is
+  excellent and closer to home — the [comparison](vs-eve.md) is honest about
+  that in both directions.
+- **Exactly-once applies to effects in your database.** A raw external call
+  with no idempotency key of its own gets at-most-once + in-doubt parking —
+  strong, but not transactional. Model money as rows (your app probably
+  already does) and you get the full guarantee.
+- **Inference goes to your configured provider.** Agent state stays in your
+  database; prompts still travel to the model you choose.
+- **Untrusted code needs a real sandbox.** The built-in Docker seam is
+  interim; configure [hermetic](https://github.com/danielstpaul/hermetic) for
+  microVM-class isolation before running code you didn't write.
+
+## Try the claim
+
+Run the template, ask for the £64 refund, clear it from the inbox — and while
+the turn is resuming, `kill -9` the worker. Restart it. The turn completes
+from its last checkpoint, and `Refund.count` is exactly 1. That's the pitch,
+reproduced on your laptop in five minutes.

data/lib/generators/silas/channel/channel_generator.rb

@@ -0,0 +1,72 @@
+require "rails/generators"
+
+module Silas
+  module Generators
+    # rails g silas:channel whatsapp
+    #
+    # A channel is two halves that must agree on one name, and hand-rolling
+    # them is where the mistakes live: inbound needs signature verification and
+    # a stable thread key, outbound needs the approval link to reach an
+    # operator. This scaffolds both, wired together, with the security
+    # decisions already made.
+    class ChannelGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Scaffold a Silas channel: outbound Channel class, inbound webhook controller, and its route."
+
+      # Channel identity is the filename (app/agent/channels/whatsapp.rb ->
+      # Agent::Channels::Whatsapp), and Registry#channels resolves it with
+      # `camelize`. A filename that isn't a snake_case identifier produces a
+      # constant Zeitwerk can't define, and the channel then fails at boot
+      # rather than here — so refuse it here, where the message is useful.
+      # (Rails' usual normalisation still applies first: `MsTeams` and
+      # `ms_teams` both land on ms_teams.)
+      def validate_name
+        return if file_name.match?(/\A[a-z_][a-z0-9_]*\z/)
+
+        raise Thor::Error, "#{file_name.inspect} is not a valid channel name — " \
+                           "it must be lowercase words separated by underscores, " \
+                           "starting with a letter (e.g. whatsapp, ms_teams)."
+      end
+
+      # Templates are .rb.tt (Rails' own convention): the .tt keeps ERB-bearing
+      # files out of the linter and off Zeitwerk's radar.
+      def create_channel
+        template "channel.rb.tt", "app/agent/channels/#{file_name}.rb"
+      end
+
+      # The webhook lives in the HOST app, not the engine: only the host knows
+      # the vendor's signature scheme and payload shape. The engine ships
+      # routes for Slack alone because it also ships Slack's verification.
+      def create_controller
+        template "controller.rb.tt", "app/controllers/agent/channels/#{file_name}_controller.rb"
+      end
+
+      def add_route
+        route %(post "/agent/channels/#{file_name}", to: "agent/channels/#{file_name}#create")
+      end
+
+      def show_next_steps
+        say <<~MSG, :green
+
+          Channel "#{file_name}" scaffolded:
+            app/agent/channels/#{file_name}.rb                        (outbound: answers + approvals)
+            app/controllers/agent/channels/#{file_name}_controller.rb (inbound: webhook)
+            config/routes.rb                                        POST /agent/channels/#{file_name}
+
+          Next:
+            1. Set the signing secret:
+               bin/rails credentials:edit  ->  silas:
+                                                 #{file_name}:
+                                                   signing_secret: ...
+            2. Fill in the three TODOs — the vendor's signature scheme, how a
+               message maps to a thread key, and how to post a message back.
+            3. Point the vendor's webhook at https://<your-host>/agent/channels/#{file_name}
+            4. Restart: app/agent/ registers at boot.
+
+          Full contract and a worked example: docs/channels.md
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/silas/channel/templates/channel.rb.tt

@@ -0,0 +1,48 @@
+# <%= class_name %> channel — OUTBOUND delivery for sessions that started in
+# <%= human_name %>. Inbound lives in
+# app/controllers/agent/channels/<%= file_name %>_controller.rb.
+#
+# Identity is this filename: <%= file_name %>.rb -> Agent::Channels::<%= class_name %>,
+# and the controller starts sessions with channel: "<%= file_name %>", which is how
+# Silas finds this class again at delivery time. Delete this file to disable
+# the channel.
+#
+# Both methods run OFF the durable loop, in ChannelDeliveryJob — so a transport
+# outage retries the delivery without re-running a single tool or touching the
+# ledger. Raising here is safe; it costs a retry, not a duplicate side effect.
+class Agent::Channels::<%= class_name %> < Silas::Channel
+  # The agent's final answer for a turn.
+  def deliver_answer(session:, text:)
+    thread = session.metadata["<%= file_name %>"] || {}
+
+    # TODO: post `text` back to the conversation. `thread` is whatever the
+    # controller stashed in metadata (chat id, phone number, message id).
+    raise NotImplementedError,
+          "Agent::Channels::<%= class_name %>#deliver_answer: post #{text.inspect} to #{thread.inspect}"
+  end
+
+  # A tool has parked for human approval; the turn is holding zero compute
+  # until someone answers. `approval_url` mints a signed, expiring one-click
+  # link that works in any transport.
+  def deliver_approval(session:, invocation:)
+    approve = Silas::Channel.approval_url(invocation, :approve)
+    decline = Silas::Channel.approval_url(invocation, :decline)
+
+    # SECURITY: an approval must reach an OPERATOR, never whoever started the
+    # session — mailing the approve link to the customer who asked for the
+    # refund lets them approve it themselves. Deliver to your ops destination
+    # (a staff channel, an on-call number), and FAIL CLOSED when it isn't
+    # configured: no destination means no approval, not a silent one.
+    operator = Rails.application.credentials.dig(:silas, :<%= file_name %>, :operator)
+    if operator.blank?
+      Rails.logger.warn("[Silas] no credentials.silas.<%= file_name %>.operator — approval for " \
+                        "invocation #{invocation.id} not delivered (won't send it to the requester).")
+      return
+    end
+
+    # TODO: send `approve` / `decline` to `operator`, with enough context to
+    # decide: invocation.tool_name and invocation.arguments.
+    raise NotImplementedError,
+          "Agent::Channels::<%= class_name %>#deliver_approval: send #{approve} / #{decline} to #{operator}"
+  end
+end

data/lib/generators/silas/channel/templates/controller.rb.tt

@@ -0,0 +1,66 @@
+# <%= class_name %> channel — INBOUND webhook. Outbound delivery lives in
+# app/agent/channels/<%= file_name %>.rb.
+#
+# Inbound is pure trigger reuse: verify the request is genuine, derive a stable
+# thread key, and hand it to Channel.dispatch — which starts a session for a new
+# thread and continues the existing one for a reply. Nothing here touches the
+# durable loop.
+class Agent::Channels::<%= class_name %>Controller < ActionController::Base
+  # A webhook carries no browser session, so no CSRF token can exist. The
+  # signature below IS the authentication — do not remove one without the other.
+  skip_forgery_protection
+
+  before_action :verify_webhook!
+
+  def create
+    # TODO: derive a STABLE thread key — the same conversation must produce the
+    # same key every time, or every message starts a new session. Use the
+    # vendor's conversation/thread id, never a per-message id.
+    thread_key = params[:conversation_id].to_s
+    text       = params[:text].to_s
+
+    return head(:ok) if thread_key.blank? || text.blank?
+
+    Agent::Channels::<%= class_name %>.dispatch(
+      thread_key: thread_key,
+      input: text,
+      # Whatever deliver_answer needs to reply. Stored on the session, so keep
+      # it small and free of secrets — it is visible in the inbox.
+      metadata: { "<%= file_name %>" => { "conversation_id" => thread_key } }
+    )
+    head :ok
+  rescue Silas::TurnInProgressError
+    # One active turn per session is an invariant, not a queue: a reply that
+    # arrives mid-turn is dropped. Tell the user, or buffer it, if that matters
+    # for your transport.
+    head :ok
+  end
+
+  private
+
+  # Rejects anything not genuinely signed. Silas::Webhook.verify_hmac handles
+  # the parts that are identical everywhere — constant-time comparison, the
+  # replay window, and failing closed when no secret is configured; you supply
+  # the vendor's shape.
+  #
+  # TODO: match your vendor's scheme. The three that vary:
+  #   payload    what they sign. Slack signs "v0:#{timestamp}:#{body}"; GitHub
+  #              and Shopify sign the raw body. It must be request.raw_post,
+  #              never re-serialized params — different bytes, different HMAC.
+  #   prefix     what they put before the digest ("v0=", "sha256=", or "").
+  #   digest     :hex (nearly everyone) or :base64 (Shopify, Twilio).
+  def verify_webhook!
+    ok = Silas::Webhook.verify_hmac(
+      secret: Rails.application.credentials.dig(:silas, :<%= file_name %>, :signing_secret),
+      signature: request.headers["X-Signature"],
+      payload: request.raw_post,
+      # Omitting a timestamp disables replay protection: a captured request can
+      # then be re-sent forever. Pass the vendor's timestamp header if it sends
+      # one, and treat its absence as a reason to check the vendor's docs.
+      timestamp: request.headers["X-Signature-Timestamp"],
+      prefix: "sha256="
+    )
+    head(:unauthorized) unless ok
+    ok
+  end
+end

data/lib/generators/silas/install/install_generator.rb

@@ -34,6 +34,15 @@ module Silas
         template "channel_email.rb", "app/agent/channels/email.rb"
       end
 
+      # A Claude Code / coding-agent skill: the app/agent/ conventions, the
+      # effect-mode and approval decision rules, and the ledger rules an agent
+      # must never violate — so a coding agent driving this app builds Silas
+      # agents correctly without the human learning the framework first.
+      # Delete the file if you don't use coding agents.
+      def create_claude_skill
+        template "claude_skill.md", ".claude/skills/silas/SKILL.md"
+      end
+
       def mount_engine
         route 'mount Silas::Engine => "/silas"'
       end
@@ -109,7 +118,8 @@ module Silas
             6. Schedules: edit app/agent/schedules/*, then `bin/rails silas:schedules`
             7. Channels (optional): set credentials.silas.slack.{signing_secret,bot_token}
                for Slack; route inbound mail to Silas::AgentMailbox for email.
-               Delete app/agent/channels/{slack,email}.rb to disable.
+               Delete app/agent/channels/{slack,email}.rb to disable. Any other
+               transport: `bin/rails g silas:channel whatsapp`.
             8. Inbox + web chat: /silas/inbox, deny-by-default — uncomment
                config.inbox_auth in config/initializers/silas.rb to make it visible.
             9. Restart your server if it was running (app/agent/ registers at boot).

data/lib/generators/silas/install/templates/claude_skill.md

@@ -0,0 +1,136 @@
+---
+name: silas
+description: Build and modify AI agents in this Rails app with the Silas gem — tools, approvals, effect modes, schedules, channels, evals. Use whenever a task touches app/agent/, app/agents/, a Silas tool, an agent's instructions or limits, or agent durability/approval behaviour.
+---
+
+# Building Silas agents
+
+Silas runs durable AI agents inside this Rails app: every turn survives
+`kill -9` and resumes from its last completed step, tool effects are
+exactly-once, and risky calls park for a human at zero compute. The agent is
+the `app/agent/` directory — you build agents by writing ordinary Ruby files
+there, not by calling a framework API.
+
+**Deep reference lives in the installed gem** — read it from the bundle when
+you need more than this file:
+
+```sh
+bundle show silas   # then read README.md, docs/*.md, DEPLOY.md there
+```
+
+## The directory is the agent
+
+```
+app/agent/
+  instructions.md   # persona (ERB; snapshotted once per turn)
+  agent.yml         # model + limits — data only, no code
+  tools/            # one file per tool; TOOL IDENTITY IS THE FILENAME
+  skills/           # markdown playbooks, loaded on demand (description: frontmatter)
+  schedules/        # cron.md (frontmatter) or .rb handlers -> silas:schedules compiles them
+  channels/         # transports (slack.rb, email.rb; generate more, see below)
+app/agents/<name>/  # NAMED agents: same tree per agent, own tools/skills/schedules
+```
+
+Files register at boot — restart the server after adding one.
+
+## Writing a tool (the part to get right)
+
+```ruby
+# app/agent/tools/issue_refund.rb  ->  tool "issue_refund"
+class Agent::Tools::IssueRefund < Silas::Tool
+  description "Refund part or all of an order."
+  param :amount_pence, :integer, desc: "Amount in pence"
+  approval ->(session:, input:) { input[:amount_pence] > 2000 ? :user_approval : :approved }
+  transactional!
+
+  def call(order_id:, amount_pence:, reason:)
+    Refund.create!(order_id:, amount_pence:, reason:)
+  end
+end
+```
+
+- **The keyword signature of `#call` IS the schema** the model sees. Keywords
+  only — never positional. `param` refines types/descriptions.
+- **Return a Hash** (anything else is wrapped as `{"value" => ...}`). Raising
+  records a failed invocation the model sees — don't rescue-and-swallow.
+- `session` is available inside `call` (the `Silas::Session` row).
+
+### Effect mode — decide by where the side effect lives
+
+| The tool… | Declare | Why |
+|---|---|---|
+| writes this app's database | `transactional!` | effect + ledger row commit atomically: **exactly-once**, even through `kill -9` |
+| calls an external API / sends anything | `at_most_once!` (the default) | a crash mid-call leaves it IN DOUBT → parks for a human verdict, never re-fires blind |
+| only reads, safe to repeat | `idempotent!` | replays re-run it freely |
+
+Never mark an external call `transactional!` — the ledger cannot roll back a
+sent email. Model money as rows in this app's own DB whenever possible; that
+is what upgrades the guarantee to exactly-once.
+
+### Approval — who holds the lever
+
+`approval :never` (default) · `:always` · `:once` (one approval per identical
+(tool, arguments) pair per session) · or a lambda returning `:user_approval`,
+`:approved`, `:not_applicable`, or `{denied: "reason"}`. Approval parks the
+turn at zero compute; a human settles it in the inbox (`/silas/inbox`), Slack,
+email, or the JSON API. Gate anything that moves money or is hard to reverse.
+
+The built-in `ask_question` tool is the reverse direction: the agent parks to
+ask the operator something and resumes with their text as the tool result.
+
+## agent.yml
+
+```yaml
+model: claude-sonnet-4-5   # must exist in ruby_llm's registry
+description: One line, shown in rosters.
+limits:
+  max_steps: 10     # model calls per turn
+  max_cost: 0.25    # dollars per turn
+  timeout: 300      # seconds of ACTIVE work — approval waits don't count
+final_answer:       # optional JSON schema -> Turn#answer_data
+  type: object
+  properties: { verdict: { type: string } }
+```
+
+Budget breaches PARK the turn (a human can top up in the inbox); they don't
+destroy work.
+
+## Rules that protect the durability contract
+
+1. **Solid Queue (or `:inline` for scripts) — never the Async adapter.** Async
+   double-executes continuation steps and silently voids exactly-once. Boot
+   raises in production if misconfigured.
+2. **Don't deploy tool/skill changes while turns are parked.** The definitions
+   digest fails a parked turn loudly on resume rather than running it against
+   a different agent (`NondeterminismError`). Settle parked turns first —
+   the same applies to toggling built-ins like `config.ask_question`.
+3. **Keep `Silas::DeadJobRescuerJob` in `config/recurring.yml`** — it is part
+   of the crash-recovery contract, and monitor worker liveness: the rescuer
+   can requeue work, it cannot conjure a consumer.
+4. **Never hand-delete `solid_queue_processes` rows** — a claimed job whose
+   process row is gone is invisible to every reaper.
+5. Tools must not spawn threads or run work outside `call` — everything the
+   ledger can't see is outside the guarantee.
+
+## Verify your work
+
+```sh
+bin/rails silas:doctor      # key, queue adapter, model, migrations, tools, rescuer
+bin/rails silas:chat        # talk to the agent from the terminal
+bin/rails silas:eval        # run test/agent_evals/*_eval.rb (deploy gate)
+```
+
+Write an eval per behaviour you care about (`Silas::Eval.scenario` — see the
+generated `test/agent_evals/example_eval.rb`). The inbox at `/silas/inbox` is
+deny-by-default: wire `config.inbox_auth` in `config/initializers/silas.rb`
+before expecting to see it.
+
+## More surface, same pattern
+
+- **Another transport**: `bin/rails g silas:channel whatsapp` scaffolds the
+  signature-verifying webhook AND the outbound half (docs/channels.md in the gem).
+- **A staff of agents**: `app/agents/<name>/` with its own tree;
+  `Silas.agent("name").start(input: ...)`; schedules in that directory tick
+  that agent.
+- **Subagents / handoffs / memory / connections (MCP)**: see the gem README —
+  each is a directory or YAML file, never an orchestration graph.

data/lib/generators/silas/install/templates/ruby_llm.rb

@@ -11,9 +11,12 @@ RubyLLM.configure do |c|
   # hasn't migrated yet — see https://rubyllm.com/upgrading-to-1-7/
   c.use_new_acts_as = true if c.respond_to?(:use_new_acts_as=)
 
+  # A nil key is inert (Silas's boot check reports "no provider configured"),
+  # so this needs no ENV guard — and the acts_as opt-in above must run even
+  # on keyless boots, or the deprecation warning returns.
   c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
   # The per-request timeout (seconds; RubyLLM default 300). Under streaming
   # this is an idle-between-chunks timeout — the hang protection for a stuck
   # provider connection.
   # c.request_timeout = 120
-end if ENV["ANTHROPIC_API_KEY"].present?
+end