silas 0.6.0 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd68f6d368466b20fbb35f49628f166ac61dd60ace3a8cbd20bbc6e316c1d346
-  data.tar.gz: 94d2a902cd7f364aa33200b1ea1f98446dabee38d9e9f7431df9cd96d1fc7f41
+  metadata.gz: 7a34eec0f8444f42ef91b1db155bc2786c28ce0de5ed345d9e63b39af9b29756
+  data.tar.gz: 94c9b0464629b6f23eab8f4811e5dd63cdec63d480388cf01c8b0b9111a43376
 SHA512:
-  metadata.gz: c386608b076c2c3dfb23e369c819a7d7b1c4fc6122f0011ea80880a46b158b25549a75388a17de250b200a60e0ada311a73df28b47c67e4007cc9e2ebef8bf3f
-  data.tar.gz: 4216b83c6925605076cb3742286699673e2a18dfd9eab3a3cc6e21479ee64e17de714737e5764acce0f147ca0023ced60ed0864b0836850c771dbab88ea84100
+  metadata.gz: 62c5e530ccc6cfbc3cbfa7b1388b72e53545172acc054b7565930eef56541f8e839846435435585db3fcc3161d40994345b0da5e24fcdc0de1710988efc7ab35
+  data.tar.gz: e8c83c1733efd76810fe2d0cd5e5e57c8b1d929d1a5556d685e376c704108c550494f07e6eb332d6968e458f1bfbb85b5fc024016d1f951dfb1d6a351b6b4683

data/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 0.6.2 (2026-07-26)
+
+The providers guide and the remaining community files.
+
+### Added
+
+- **`docs/providers.md` — Providers & gateways.** How a model id picks a
+  provider (and why Silas stamps the resolved provider on every step row),
+  the OpenRouter recipe — one key, 300+ models, slash-form ids, with cost
+  lines and `compact_at` following the registry entry for the route you
+  actually run — plus OpenAI-compatible gateways (LiteLLM, Vercel AI
+  Gateway) via `openai_api_base`/`openrouter_api_base`, the
+  Bedrock/Vertex/Azure key map, local runtimes with the honest
+  cost-unavailable story, and `around_model_call` for failover. Every
+  mechanical claim verified against ruby_llm 1.16 source and a live
+  resolution run; Vercel endpoint details from their docs as of 2026-07-07.
+  Ships in the gem; linked from the configuration reference, the README,
+  and the installer's `ruby_llm.rb` initializer comment.
+- **`CODE_OF_CONDUCT.md`** (Contributor Covenant 2.1), linked from
+  CONTRIBUTING and the README.
+- **A pull request template** mirroring CONTRIBUTING's actual gates: both
+  stores, RuboCop, the chaos gate when the loop is touched, the
+  templates-smoke run when generators change, and a durability-notes
+  section for replay-path changes.
+
+### Fixed
+
+- README's status line claimed 0.5.x.
+
+## 0.6.1 (2026-07-26)
+
+Two live-inbox fixes found by driving real apps, a security hardening pass,
+and the polished brand kit.
+
+### Changed
+
+- **Polished brand geometry everywhere.** Lamps sit on a shared r4.8 circle
+  (proceed and held aspects now one geometry), the favicon is redrawn
+  natively at 32px with a heavier housing (it reads at 16px now), and the
+  wordmark lockup is cropped to the ink — re-outlined to font-independent
+  paths on the new geometry. The inbox layout's favicon and header mark
+  carry the new coordinates, as do the templates' landing pages.
+- The docs gained real product imagery: an 18-frame park→approve→clear GIF
+  captured from a genuine template-app run, the held approval card, and the
+  signal board — on the site landing, inbox-and-api, and tutorial pages.
+
+### Fixed
+
+- **The turn pill now flips to held live.** Turbo `replace` swaps the target
+  element itself, but the header's and cost line's broadcast-target ids lived
+  on wrapper divs in the parent views — so the FIRST status broadcast
+  destroyed the target and every later one (including the park that reads
+  **held**) silently no-opped until a reload. The partials now carry their own
+  root ids, with regression specs asserting a replace re-emits its target.
+- **The first broadcast of a fresh worker no longer dies on lazy routes.**
+  Rails 8.1's lazy route set only retries a missing url helper when the app
+  routes were *just* loaded; in a worker's first Turbo render the engine's
+  helper module could predate its route draw, killing the job silently
+  (`undefined method 'cancel_inbox_turn_path'`). `silas_engine_path` now
+  forces the draw once on miss.
+
+### Security
+
+- **Connections refuse credentials over plaintext http.** A connection with
+  `auth:` configured and an `http://` URL to a remote host now fails loudly at
+  parse time (localhost exempt; unparseable URLs with auth fail closed).
+  Finding from the pre-release security audit — which otherwise confirmed the
+  posture: fail-closed HMAC webhook verification with constant-time compare
+  and a replay window, expiring signed approval tokens, deny-by-default
+  inbox/API auth enforced at the base controllers, argv-array sandbox exec
+  (no shell interpolation), timing-safe MCP token compare, restricted ERB
+  bindings, no interpolated SQL, Brakeman and bundler-audit clean.
+
 ## 0.6.0 (2026-07-26)
 
 The brand release: the Signals inbox, the docs surface (site + gem-shipped

data/README.md

@@ -100,9 +100,11 @@ release): [guarantees](https://danielstpaul.github.io/silas/guarantees).
 
 ## Status
 
-Early (0.5.x) and moving fast. Requires Rails >= 8.1 (Active Job
+Early (0.6.x) and moving fast. Requires Rails >= 8.1 (Active Job
 Continuations) and Solid Queue >= 1.2; any model provider
-[RubyLLM](https://rubyllm.com) supports.
+[RubyLLM](https://rubyllm.com) supports — Anthropic direct, OpenRouter,
+OpenAI-compatible gateways, local runtimes
+([providers guide](https://github.com/danielstpaul/silas/blob/main/docs/providers.md)).
 
 ## Community
 
@@ -113,7 +115,9 @@ Questions, ideas, and bug reports →
 
 See [CONTRIBUTING.md](https://github.com/danielstpaul/silas/blob/main/CONTRIBUTING.md)
 — including the short list of things Silas deliberately doesn't do, and the
-chaos gate that protects the durability contract.
+chaos gate that protects the durability contract. Everyone interacting here
+is expected to follow the
+[code of conduct](https://github.com/danielstpaul/silas/blob/main/CODE_OF_CONDUCT.md).
 
 ## Security
 

data/app/helpers/silas/inbox/trace_helper.rb

@@ -65,7 +65,15 @@ module Silas
       # bare broadcast renderer doesn't have — so broadcast-rendered partials
       # build paths from the engine's own route set + the discovered mount.
       def silas_engine_path(helper, *args)
-        Silas::Engine.routes.url_helpers.public_send(helper, *args, script_name: Silas::Inbox.mount_path)
+        helpers = Silas::Engine.routes.url_helpers
+        # Rails 8.1's lazy route set: in a worker's FIRST broadcast render the
+        # engine's helper module can predate its route draw, and the lazy
+        # method_missing only retries when the app routes were *just* loaded —
+        # otherwise it raises NoMethodError and the Turbo job dies silently
+        # (observed: the first turn broadcast of a fresh worker). Force the
+        # draw once on miss; every later call takes the fast path.
+        Rails.application.reload_routes! unless helpers.respond_to?(helper)
+        helpers.public_send(helper, *args, script_name: Silas::Inbox.mount_path)
       end
     end
   end

data/app/views/layouts/silas/inbox.html.erb

@@ -5,7 +5,7 @@
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title><%= content_for?(:title) ? yield(:title) : "Silas Inbox" %></title>
   <%# The night tile, inlined — the engine ships no assets and keeps shipping none. %>
-  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%230F1013'/%3E%3Cg transform='translate(4,4)'%3E%3Ccircle cx='12' cy='12' r='9.6' fill='none' stroke='%23E9EBEF' stroke-width='2.2'/%3E%3Ccircle cx='8.4' cy='15.6' r='2.5' fill='%23F2F4F8'/%3E%3Ccircle cx='15.6' cy='8.4' r='2.5' fill='%23F2F4F8'/%3E%3C/g%3E%3C/svg%3E">
+  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='32' height='32' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='7' fill='%230F1013'/%3E%3Ccircle cx='16' cy='16' r='10.8' fill='none' stroke='%23E9EBEF' stroke-width='2.5'/%3E%3Ccircle cx='12.18' cy='19.82' r='2.8' fill='%23F2F4F8'/%3E%3Ccircle cx='19.82' cy='12.18' r='2.8' fill='%23F2F4F8'/%3E%3C/svg%3E">
   <% if Silas::Inbox.streaming_available? %><%= turbo_include_tags rescue nil %><% end %>
   <style>
     /* Direction "Signals" (see docs/conventions.md and the brand book).
@@ -160,7 +160,7 @@
           <%# The mark: a position-light signal, diagonal = "proceed". Bezel in
               ink, lamps in the accent — so the lamps are white at night and
               route-blue on paper, per the one-token-may-change-hue rule. %>
-          <svg width="22" height="22" viewBox="0 0 24 24" fill="none" role="img" aria-hidden="true"><circle cx="12" cy="12" r="9.6" fill="none" style="stroke: var(--ink)" stroke-width="2.2"/><circle cx="8.4" cy="15.6" r="2.5" style="fill: var(--accent)"/><circle cx="15.6" cy="8.4" r="2.5" style="fill: var(--accent)"/></svg><span>silas</span>
+          <svg width="22" height="22" viewBox="0 0 24 24" fill="none" role="img" aria-hidden="true"><circle cx="12" cy="12" r="9.6" fill="none" style="stroke: var(--ink)" stroke-width="2.2"/><circle cx="8.61" cy="15.39" r="2.5" style="fill: var(--accent)"/><circle cx="15.39" cy="8.61" r="2.5" style="fill: var(--accent)"/></svg><span>silas</span>
         <% end %>
       </span>
       <span class="spacer"></span>

data/app/views/silas/inbox/sessions/_cost.html.erb

@@ -1 +1,3 @@
-<span class="cost"><%= cost_label(Silas::Inbox::Cost.for_session(session)) %></span>
+<%# Root id = the broadcast target (replaced after every completed step); it
+    must be in the partial or the first replace erases the target. %>
+<span class="cost" id="silas-session-<%= session.id %>-cost"><%= cost_label(Silas::Inbox::Cost.for_session(session)) %></span>

data/app/views/silas/inbox/sessions/show.html.erb

@@ -12,7 +12,7 @@
     <span class="muted">#<%= @session.id %></span>
   </div>
   <div class="muted"><%= @session.channel.presence || "direct" %> · started <%= silas_relative_time(@session.created_at) %></div>
-  <div id="silas-session-<%= @session.id %>-cost"><%= render "silas/inbox/sessions/cost", session: @session %></div>
+  <%= render "silas/inbox/sessions/cost", session: @session %>
 </div>
 
 <%# 04: everything awaiting a person sits ABOVE the movement — the operator

data/app/views/silas/inbox/turns/_header.html.erb

@@ -1,28 +1,34 @@
-<div class="turn-head">
-  <span class="turn-input"><%= truncate(turn.input, length: 90) %></span>
-  <%= status_pill(turn.status) %>
-  <% if turn.active? && !turn.cancel_requested_at %>
-    <%# silas_engine_path — this partial is broadcast-rendered through the
-        host renderer on every turn status change; bare engine helpers (and
-        the scope-dependent mounted proxy) 500 there. %>
-    <%= form_with url: silas_engine_path(:cancel_inbox_turn_path, turn), method: :post, class: "inline" do %>
-      <button class="btn-cancel" title="Honored at the next step boundary">Cancel</button>
+<%# The root id IS the broadcast target (Broadcastable replaces
+    silas-turn-<id>-header on every status change). It must live HERE, not on
+    a wrapper in the parent: Turbo `replace` swaps the target element itself,
+    so a partial without the id would erase the target on first use. %>
+<div id="silas-turn-<%= turn.id %>-header">
+  <div class="turn-head">
+    <span class="turn-input"><%= truncate(turn.input, length: 90) %></span>
+    <%= status_pill(turn.status) %>
+    <% if turn.active? && !turn.cancel_requested_at %>
+      <%# silas_engine_path — this partial is broadcast-rendered through the
+          host renderer on every turn status change; bare engine helpers (and
+          the scope-dependent mounted proxy) 500 there. %>
+      <%= form_with url: silas_engine_path(:cancel_inbox_turn_path, turn), method: :post, class: "inline" do %>
+        <button class="btn-cancel" title="Honored at the next step boundary">Cancel</button>
+      <% end %>
+    <% elsif turn.cancel_requested_at && turn.active? %>
+      <span class="muted">cancel requested…</span>
     <% end %>
-  <% elsif turn.cancel_requested_at && turn.active? %>
-    <span class="muted">cancel requested…</span>
+  </div>
+  <% if turn.budget_parked? %>
+    <div class="approval">
+      <h3>Budget reached — <%= turn.failure_reason %></h3>
+      <div class="muted">Parked at zero compute. Raise the limit and the turn resumes
+        by replaying completed work from rows — no re-calls, no re-effects.</div>
+      <%= form_with url: silas_engine_path(:raise_budget_inbox_turn_path, turn), method: :post, class: "topup-form" do %>
+        <input name="value" type="number" step="any" min="0" required class="topup-input"
+               placeholder="<%= turn.failure_reason == "max_cost" ? "new limit in dollars, e.g. 2.50" : "new limit, e.g. 200000" %>">
+        <button class="btn approve">Raise &amp; resume</button>
+      <% end %>
+    </div>
+  <% elsif turn.failure_reason.present? %>
+    <div class="muted">failed: <%= turn.failure_reason %></div>
   <% end %>
 </div>
-<% if turn.budget_parked? %>
-  <div class="approval">
-    <h3>Budget reached — <%= turn.failure_reason %></h3>
-    <div class="muted">Parked at zero compute. Raise the limit and the turn resumes
-      by replaying completed work from rows — no re-calls, no re-effects.</div>
-    <%= form_with url: silas_engine_path(:raise_budget_inbox_turn_path, turn), method: :post, class: "topup-form" do %>
-      <input name="value" type="number" step="any" min="0" required class="topup-input"
-             placeholder="<%= turn.failure_reason == "max_cost" ? "new limit in dollars, e.g. 2.50" : "new limit, e.g. 200000" %>">
-      <button class="btn approve">Raise &amp; resume</button>
-    <% end %>
-  </div>
-<% elsif turn.failure_reason.present? %>
-  <div class="muted">failed: <%= turn.failure_reason %></div>
-<% end %>

data/app/views/silas/inbox/turns/_turn.html.erb

@@ -1,7 +1,9 @@
 <div class="turn" id="<%= dom_id(turn) %>">
-  <div id="silas-turn-<%= turn.id %>-header">
-    <%= render "silas/inbox/turns/header", turn: turn %>
-  </div>
+  <%# The header partial carries its own broadcast-target id: Turbo `replace`
+      swaps the TARGET ELEMENT itself, so if the id lived on a wrapper here,
+      the first status broadcast would destroy it and every later transition
+      (including the park that flips the pill to held) would silently no-op. %>
+  <%= render "silas/inbox/turns/header", turn: turn %>
   <div id="silas-turn-<%= turn.id %>-steps">
     <%= render partial: "silas/inbox/steps/step", collection: turn.steps, as: :step %>
   </div>

data/docs/configuration.md

@@ -18,6 +18,10 @@ end
 | `around_model_call` | `nil` | Wrap every model call — e.g. `->(ctx, &call) { RubyLLM::Resilience.chain(:anthropic) { call.() } }`. |
 | `queue_name` | `:default` | Active Job queue for agent turns. |
 
+Which provider serves a turn is decided by the model id — OpenRouter,
+OpenAI-compatible gateways, Bedrock/Vertex/Azure, and local runtimes are all
+recipes in [providers](providers.md).
+
 ## The loop
 
 | Option | Default | Meaning |

data/docs/connections.md

@@ -29,6 +29,9 @@ through the same Ledger.
   join your database transaction, so the honest ceiling is `at_most_once`
   (an ambiguous crash parks in-doubt for a person) or `idempotent` (you're
   asserting the remote op is safe to repeat).
+- **Credentials require https.** A connection with `auth:` configured and a
+  plaintext `http://` URL fails loudly at parse time (localhost is exempt for
+  local development servers).
 - **Transport is HTTP** (v1). Filename is the namespace: `crm.yml` →
   `crm__*`.
 

data/docs/inbox-and-api.md

@@ -13,6 +13,13 @@ hoisted to the top of the session, a full audit trail (every tool call's
 arguments and result, who cleared what and why), cancel, raise-budget, and
 per-session token/cost accounting priced from RubyLLM's model registry.
 
+<img src="https://raw.githubusercontent.com/danielstpaul/silas/main/docs/img/silas-inbox-held.png" width="740"
+     alt="A session held at the signal: the amber approval card for issue_refund hoisted above the trace, with the turn marked HELD and a held-at-the-signal stub in place">
+
+A £64 refund holding at the signal: the card carries the exact arguments, the
+turn costs nothing while it waits, and the trace below keeps a one-line stub
+where the invocation held.
+
 It's **deny-by-default** — invisible until you wire auth:
 
 ```ruby

data/docs/providers.md

@@ -0,0 +1,171 @@
+# Providers & gateways
+
+Silas has exactly one inference seam: the `:ruby_llm` adapter. Every model
+call goes through [RubyLLM](https://rubyllm.com), so every provider RubyLLM
+speaks — Anthropic, OpenAI, Gemini, Bedrock, Vertex AI, Azure, Mistral,
+DeepSeek, Perplexity, xAI, OpenRouter, local runtimes — is available to your
+agents with zero Silas-specific glue. Keys live in
+`config/initializers/ruby_llm.rb`; **which provider serves a turn is decided
+by the model id**. Nothing in `app/agent/` changes when the provider does.
+
+## How a model id picks a provider
+
+RubyLLM ships a model registry (1,100+ entries, refreshed upstream from
+[models.dev](https://models.dev)). Silas resolves the agent's `model:` — from
+`agent.yml`, falling back to `config.default_model` — against that registry;
+the matching entry names the provider, and the adapter builds that provider's
+client. The same entry supplies the numbers Silas runs on, per
+(model, provider):
+
+- **pricing** — the cost lines in the inbox and the `max_cost` budget;
+- **context window** — the `compact_at` compaction threshold.
+
+So switching provider is switching model id. A model the registry doesn't
+know fails fast at the first step with the fix in the error
+(`RubyLLM.models.refresh!`, or pick a registry model). And because a
+registry's tie-breaks can change across upgrades, Silas stamps the resolved
+provider on every step row — historical cost lines price against the
+(model, provider) that actually served them, forever.
+
+## Direct providers
+
+The installer's `config/initializers/ruby_llm.rb` maps environment keys in —
+RubyLLM never reads provider keys from the environment by itself:
+
+```ruby
+RubyLLM.configure do |c|
+  c.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+end
+```
+
+Every provider follows the same pattern (`openai_api_key`,
+`gemini_api_key`, …— the full list is in
+[RubyLLM's configuration docs](https://rubyllm.com/configuration/)). For
+cloud-platform shops the "enterprise gateway" is usually just the native
+provider:
+
+| Platform | Keys |
+|---|---|
+| AWS Bedrock | `bedrock_api_key`, `bedrock_secret_key`, `bedrock_region` (+ optional `bedrock_session_token`) |
+| GCP Vertex AI | `vertexai_project_id`, `vertexai_location` (+ optional `vertexai_service_account_key`) |
+| Azure OpenAI | `azure_api_base`, `azure_api_key` (or `azure_ai_auth_token`) |
+
+Verify any of this with `bin/rails silas:doctor` — it reports which providers
+have credentials configured and resolves your default model with its price:
+
+```
+ ✓ provider credentials — anthropic
+ ✓ model claude-sonnet-4-5 — anthropic · $3/$15 per MTok
+```
+
+## OpenRouter: one key, 300+ models
+
+[OpenRouter](https://openrouter.ai) is a first-class RubyLLM provider, and
+the registry ships its catalog (341 models as of ruby_llm 1.16) — one key
+buys your agents Claude, GPT, Gemini, Llama, DeepSeek and the rest, billed
+in one place.
+
+```ruby
+# config/initializers/ruby_llm.rb
+RubyLLM.configure do |c|
+  c.openrouter_api_key = ENV["OPENROUTER_API_KEY"]
+end
+```
+
+Routed models use slash-form ids — `creator/model`, exactly as OpenRouter
+lists them:
+
+```yaml
+# app/agent/agent.yml
+model: anthropic/claude-sonnet-4.5   # via OpenRouter
+```
+
+or globally:
+
+```ruby
+Silas.configure do |c|
+  c.default_model = "anthropic/claude-sonnet-4.5"
+end
+```
+
+The two id families never collide: `claude-sonnet-4-5` is Anthropic direct,
+`anthropic/claude-sonnet-4.5` is the same model via OpenRouter, and each
+resolves to its own registry entry. That per-route entry is the one your
+cost lines and compaction thresholds follow — the route you run, not the
+origin provider. Concretely, in the shipped registry the direct entry lists
+a 200K context window while OpenRouter's route lists 1M, so `compact_at`
+triggers where the route actually overflows.
+
+`silas:doctor` confirms the whole chain:
+
+```
+ ✓ provider credentials — openrouter
+ ✓ model anthropic/claude-sonnet-4.5 — openrouter · $3/$15 per MTok
+```
+
+## OpenAI-compatible gateways
+
+Self-hosted and enterprise gateways (LiteLLM, Vercel AI Gateway, an internal
+proxy) mostly speak the OpenAI chat-completions dialect. Two shapes:
+
+**The gateway serves OpenAI model ids** (`gpt-5.2`, …) — point the OpenAI
+provider at it:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openai_api_key  = ENV["GATEWAY_API_KEY"]
+  c.openai_api_base = "https://gateway.internal/v1"
+end
+```
+
+**The gateway serves models.dev slash ids** (`anthropic/claude-sonnet-4.5`,
+…, as Vercel's AI Gateway does) — repoint the OpenRouter provider, which
+already speaks plain chat-completions against exactly those ids:
+
+```ruby
+RubyLLM.configure do |c|
+  c.openrouter_api_key  = ENV["AI_GATEWAY_API_KEY"]
+  c.openrouter_api_base = "https://ai-gateway.vercel.sh/v1"
+end
+```
+
+Either way the model id must still resolve in the registry — the registry
+entry is where Silas gets pricing and the context window, and a gateway
+that bills differently can be corrected per model with the
+`config.model_prices` override ([configuration](configuration.md)).
+
+Two gateway footnotes, both cheap to check with one real turn:
+
+- RubyLLM renders system messages as role `developer` (OpenAI's current
+  dialect) through these providers. OpenRouter normalises it; if your
+  gateway insists on `system`, set `c.openai_use_system_role = true`.
+- Streaming must pass through as SSE. If the operator inbox shows a turn
+  completing without live text, the gateway buffered the stream.
+
+## Local runtimes
+
+Ollama and GPUStack are RubyLLM providers too (`ollama_api_base`,
+`gpustack_api_base`/`gpustack_api_key`). Local models aren't in the shipped
+registry, so refresh it after configuring — `RubyLLM.models.refresh!` asks
+every configured provider for its live model list and merges the results —
+then use the id it lists. Local models carry no registry pricing: the inbox
+shows their token counts with "cost unavailable", and a `max_cost` budget
+can't bind (only priced tokens count toward it) — list the model in
+`config.model_prices` to restore both.
+
+## Failover and wrapping
+
+Provider outages, rate-limit retries and model failover belong at the
+inference seam, not in your tools. `config.around_model_call` wraps every
+model call the loop makes:
+
+```ruby
+Silas.configure do |c|
+  c.around_model_call = ->(ctx, &call) do
+    RubyLLM::Resilience.chain(:anthropic) { call.() }
+  end
+end
+```
+
+Whatever runs inside still lands in the same durable step — a failover
+retry that succeeds is recorded exactly like a first-try success.

data/docs/tutorial.md

@@ -15,8 +15,12 @@ rails new desk -m https://raw.githubusercontent.com/danielstpaul/silas/main/temp
 cd desk && bin/dev
 ```
 
-Open <http://localhost:3000> — the **signal board** — then *operator inbox →*
-and start a session:
+Open <http://localhost:3000> — the **signal board**:
+
+<img src="https://raw.githubusercontent.com/danielstpaul/silas/main/docs/img/silas-board.png" width="740"
+     alt="The desk's signal board: aspect tiles for held/working/clear/in doubt, the keyless demo banner, the agent card, and try-it prompts">
+
+Then *operator inbox →* and start a session:
 
 > The walnut monitor stand (order R-1002) arrived cracked.
 

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

@@ -3,7 +3,9 @@
 #
 #   export ANTHROPIC_API_KEY=sk-ant-...
 #
-# Any provider RubyLLM supports works the same way (openai_api_key, etc.).
+# Any provider RubyLLM supports works the same way (openai_api_key, etc.) —
+# OpenRouter, OpenAI-compatible gateways, and local runtimes are covered in
+# the Silas guide docs/providers.md (shipped in the gem: `bundle show silas`).
 RubyLLM.configure do |c|
   # Silas never uses RubyLLM's acts_as_* ActiveRecord mixins (it owns its own
   # durable schema), so opt into the new API to silence the legacy deprecation

data/lib/silas/connection.rb

@@ -51,6 +51,22 @@ module Silas
       raise Error, "connection #{name}: transport #{transport.inspect} unsupported (v1: http)" unless TRANSPORTS.include?(transport)
       raise Error, "connection #{name}: approval #{approval.inspect} invalid" unless APPROVALS.include?(approval)
       raise Error, "connection #{name}: effect #{effect.inspect} invalid" unless EFFECTS.include?(effect)
+      # Never send a credential over plaintext: an auth'd connection must be
+      # https (loopback exempt for local development servers). Boot-time and
+      # loud, like every other connection misconfiguration.
+      if @auth["type"].present? && plaintext_remote?
+        raise Error, "connection #{name}: refusing to send credentials over plaintext http — " \
+                     "use https (localhost/127.0.0.1 are exempt)"
+      end
+    end
+
+    def plaintext_remote?
+      uri = URI(url)
+      # Scheme case-insensitively (HTTP:// is still plaintext); URI#host keeps
+      # brackets on IPv6 literals, so the loopback exemption lists both forms.
+      uri.scheme&.downcase == "http" && !%w[localhost 127.0.0.1 ::1 [::1]].include?(uri.host)
+    rescue URI::InvalidURIError
+      true # an unparseable url with auth configured fails closed
     end
 
     # One remote tool, resolved. Quacks like a resolved Silas::Tool for the

data/lib/silas/version.rb

@@ -1,3 +1,3 @@
 module Silas
-  VERSION = "0.6.0"
+  VERSION = "0.6.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: silas
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.2
 platform: ruby
 authors:
 - Daniel St Paul
@@ -177,6 +177,7 @@ files:
 - docs/guarantees.md
 - docs/inbox-and-api.md
 - docs/memory.md
+- docs/providers.md
 - docs/sandbox.md
 - docs/tools.md
 - docs/tutorial.md