silas 0.4.0 → 0.6.0

data/docs/channels.md

@@ -0,0 +1,290 @@
+# Channels
+
+A channel puts your agent somewhere people already are — Slack, email, WhatsApp,
+Discord, SMS, your own app's webhook — without changing the agent itself. The
+same tools, the same approvals, the same ledger. Only the surface changes.
+
+```bash
+bin/rails generate silas:channel whatsapp
+```
+
+That scaffolds both halves and the route that joins them. The rest of this page
+is the contract they implement, so you can fill in the three TODOs correctly and
+know what you're getting for free.
+
+---
+
+## The two halves
+
+A channel is inbound and outbound, and they are deliberately separate: inbound is
+a web request, outbound is a background job. They meet at one name.
+
+```
+app/agent/channels/whatsapp.rb                        outbound  Agent::Channels::Whatsapp
+app/controllers/agent/channels/whatsapp_controller.rb inbound   Agent::Channels::WhatsappController
+config/routes.rb                                      POST /agent/channels/whatsapp
+```
+
+**Identity is the filename.** `whatsapp.rb` defines `Agent::Channels::Whatsapp`,
+sessions started through it carry `channel: "whatsapp"`, and Silas uses that
+string to find the class again at delivery time. Rename the file and the channel
+is renamed; delete it and the channel is gone.
+
+The webhook controller lives in **your app**, not the engine, because only your
+app knows the vendor's signature scheme and payload shape. Slack is the one
+exception — Silas ships its routes and verification because it ships Slack's
+whole dialect.
+
+---
+
+## Inbound: verify, key, dispatch
+
+```ruby
+class Agent::Channels::WhatsappController < ActionController::Base
+  skip_forgery_protection          # no browser session -> no CSRF token can exist
+  before_action :verify_webhook!   # ...so the signature IS the authentication
+
+  def create
+    Agent::Channels::Whatsapp.dispatch(
+      thread_key: params[:conversation_id].to_s,
+      input: params[:text].to_s,
+      metadata: { "whatsapp" => { "conversation_id" => params[:conversation_id] } }
+    )
+    head :ok
+  rescue Silas::TurnInProgressError
+    head :ok
+  end
+end
+```
+
+`dispatch` is the whole inbound API. It maps the external thread to a session and
+then calls the ordinary public API — `Silas.agent.start` for a new thread,
+`session.continue` for a reply. There is no channel-specific loop.
+
+Three things to get right:
+
+**The thread key must be stable.** The same conversation must produce the same
+key every time, or every message starts a new session and the agent has no
+memory. Use the vendor's conversation or thread id, never a per-message id. Keys
+are namespaced by channel (`whatsapp:abc123`), so two channels can't collide.
+
+**Sign over the raw body.** `request.raw_post`, never re-serialized params —
+re-serializing changes the bytes and the HMAC no longer matches. See
+[Verification](#verification) below.
+
+**One active turn per session is an invariant, not a queue.** A reply that
+arrives while the agent is still working raises `Silas::TurnInProgressError`. The
+generated controller answers `200` so the vendor stops retrying; if dropping the
+message matters for your transport, buffer it or tell the user.
+
+Metadata is stored on the session and shown in the inbox, so keep it small and
+free of secrets. It exists so outbound knows where to reply.
+
+### Verification
+
+`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:
+
+```ruby
+Silas::Webhook.verify_hmac(
+  secret:    Rails.application.credentials.dig(:silas, :whatsapp, :signing_secret),
+  signature: request.headers["X-Signature"],
+  payload:   request.raw_post,   # what they signed
+  timestamp: request.headers["X-Signature-Timestamp"],
+  prefix:    "sha256=",          # what they put before the digest
+  digest:    :hex                # :hex, or :base64 for Shopify/Twilio
+)
+```
+
+Vendors differ only in three places:
+
+| Vendor | `payload` | `prefix` | `digest` |
+|---|---|---|---|
+| Slack | `"v0:#{timestamp}:#{body}"` | `"v0="` | `:hex` |
+| GitHub | raw body | `"sha256="` | `:hex` |
+| Shopify | raw body | `""` | `:base64` |
+
+Omitting `timestamp:` disables replay protection — a captured request can then be
+re-sent forever. If your vendor doesn't send one, that's worth knowing rather
+than defaulting past.
+
+---
+
+## Outbound: answers and approvals
+
+```ruby
+class Agent::Channels::Whatsapp < Silas::Channel
+  def deliver_answer(session:, text:)
+    # post `text` back to session.metadata["whatsapp"]
+  end
+
+  def deliver_approval(session:, invocation:)
+    approve = Silas::Channel.approval_url(invocation, :approve)
+    decline = Silas::Channel.approval_url(invocation, :decline)
+    # send those two links to an OPERATOR
+  end
+end
+```
+
+You never call these. `ChannelDeliveryJob` does, from `after_commit` callbacks —
+`deliver_answer` when a turn completes or fails, `deliver_approval` the moment a
+tool parks. Both run **off the durable loop**, which is the important part: 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.
+
+Delivery is claimed compare-and-swap on a marker column (`answered_at`,
+`notified_at`) and released if your method raises, so a retry re-attempts rather
+than double-sending. A duplicate ping is the worst case; it is never a ledger
+violation.
+
+### Approval links
+
+`Silas::Channel.approval_url` mints a signed, expiring one-click link that works
+in any transport — a WhatsApp message, a Discord embed, an SMS. Possession of the
+link is the credential, so it needs no session and no login, and it expires with
+`config.approval_ttl` (7 days by default).
+
+It needs a host, and never guesses one — a hostless approval link is a dead link:
+
+```ruby
+config.action_mailer.default_url_options = { host: "yourapp.com" }
+```
+
+> **Send approvals to an operator, never to the requester.**
+> For a customer-facing channel, `session.metadata` describes the person who
+> messaged in. Sending them the approve link lets them approve their own refund.
+> Deliver to your ops destination instead, and **fail closed** when it isn't
+> configured — no destination means no approval, not a silent one. The generated
+> channel does this; keep it.
+
+Slack is different only because it can do better: it renders real Approve/Decline
+buttons via Block Kit, handled by the engine's own actions webhook. Every other
+transport uses the signed link.
+
+---
+
+## What you get for free
+
+Everything that makes the agent durable is already there, because a channel is a
+trigger, not a runtime:
+
+- **Crash-safe turns.** Kill the worker mid-conversation; the turn resumes where
+  it stopped, and no tool runs twice.
+- **Approvals that park at zero compute.** A parked turn holds no worker, no
+  memory, no tokens. It can wait days.
+- **The inbox.** Every channel session appears at `/silas/inbox` with its full
+  trace — you can watch and approve a WhatsApp conversation from the operator UI
+  without building anything.
+- **Budgets, cancellation, evals, memory.** All unchanged.
+
+A channel is also **not** in the definitions digest — it's a transport, not a
+model-visible capability — so adding or changing one never fails a parked turn
+with `NondeterminismError`.
+
+---
+
+## Worked example: WhatsApp Cloud API
+
+```bash
+bin/rails generate silas:channel whatsapp
+bin/rails credentials:edit
+```
+
+```yaml
+silas:
+  whatsapp:
+    signing_secret: <your app secret>
+    operator: "+441234567890"
+    token: <your permanent access token>
+    phone_number_id: "123456789"
+```
+
+Meta signs the raw body with your app secret and prefixes `sha256=`:
+
+```ruby
+# app/controllers/agent/channels/whatsapp_controller.rb
+def verify_webhook!
+  ok = Silas::Webhook.verify_hmac(
+    secret: Rails.application.credentials.dig(:silas, :whatsapp, :signing_secret),
+    signature: request.headers["X-Hub-Signature-256"],
+    payload: request.raw_post,
+    prefix: "sha256="   # Meta sends no timestamp header: no replay window
+  )
+  head(:unauthorized) unless ok
+  ok
+end
+
+def create
+  message = params.dig(:entry, 0, :changes, 0, :value, :messages, 0)
+  return head(:ok) unless message && message[:type] == "text"
+
+  Agent::Channels::Whatsapp.dispatch(
+    thread_key: message[:from],            # the sender's number: stable per conversation
+    input: message.dig(:text, :body).to_s,
+    metadata: { "whatsapp" => { "to" => message[:from] } }
+  )
+  head :ok
+rescue Silas::TurnInProgressError
+  head :ok
+end
+```
+
+```ruby
+# app/agent/channels/whatsapp.rb
+class Agent::Channels::Whatsapp < Silas::Channel
+  def deliver_answer(session:, text:)
+    send_text(to: session.metadata.dig("whatsapp", "to"), body: text)
+  end
+
+  def deliver_approval(session:, invocation:)
+    operator = Rails.application.credentials.dig(:silas, :whatsapp, :operator)
+    if operator.blank?
+      Rails.logger.warn("[Silas] no operator configured — approval #{invocation.id} not delivered")
+      return
+    end
+
+    send_text(to: operator, body: <<~MSG)
+      Approval needed: #{invocation.tool_name}
+      #{JSON.pretty_generate(invocation.arguments)}
+
+      Approve: #{Silas::Channel.approval_url(invocation, :approve)}
+      Decline: #{Silas::Channel.approval_url(invocation, :decline)}
+    MSG
+  end
+
+  private
+
+  def send_text(to:, body:)
+    credentials = Rails.application.credentials.silas[:whatsapp]
+    uri = URI("https://graph.facebook.com/v20.0/#{credentials[:phone_number_id]}/messages")
+    response = Net::HTTP.post(
+      uri,
+      { messaging_product: "whatsapp", to: to, type: "text", text: { body: body } }.to_json,
+      "content-type" => "application/json",
+      "authorization" => "Bearer #{credentials[:token]}"
+    )
+    # Raise on failure: ChannelDeliveryJob releases its claim and retries.
+    raise Silas::Error, "WhatsApp send failed: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
+  end
+end
+```
+
+Point Meta's webhook at `https://yourapp.com/agent/channels/whatsapp` and restart
+— `app/agent/` registers at boot.
+
+---
+
+## Why Silas ships one channel and a generator
+
+Slack is first-party because it ships a whole dialect: signature scheme, Block
+Kit approvals, an interactive-actions webhook. Every other transport is a
+different vendor's API drifting on its own schedule, and a framework that
+promises to keep six of those working is a framework that breaks.
+
+The generator is the leverage instead. It gets the security decisions right —
+signature-first, raw body, fail closed, operators not requesters — and leaves the
+vendor's three variables to you.
+
+If you build one worth sharing, open a PR against this page.

data/docs/configuration.md

@@ -0,0 +1,106 @@
+# Configuration reference
+
+Everything lives in one block, usually in `config/initializers/silas.rb` (the
+installer generates a commented starter):
+
+```ruby
+Silas.configure do |c|
+  # ...
+end
+```
+
+## Inference
+
+| Option | Default | Meaning |
+|---|---|---|
+| `adapter` | `:ruby_llm` | The inference seam. `:ruby_llm` (any provider RubyLLM supports), or any object responding to `#execute_step` — the eval harness, the chaos suite, and the template's keyless demo all inject one. |
+| `default_model` | `"claude-sonnet-4-5"` | Used when `agent.yml` doesn't set `model:`. Must resolve in your installed RubyLLM registry. |
+| `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. |
+
+## The loop
+
+| Option | Default | Meaning |
+|---|---|---|
+| `max_steps` | `25` | Hard cap on model calls per turn; `agent.yml` `limits.max_steps` overrides per agent. Hitting it fails the turn (`max_steps`). |
+| `compact_at` | `0.9` | Context compaction trigger. A Float in (0, 1] = fraction of the model's registry context window; an Integer = absolute token threshold (the form custom adapters need); `nil`/`false` disables. Compaction summarises **prior turns** into a persisted, exactly-once row — the current turn is never compacted, and replays stay byte-identical. |
+| `isolate_steps` | `true` | Continuation isolation per step — the durability contract. Leave on; specs may disable for inline runs. |
+
+## Approvals & questions
+
+| Option | Default | Meaning |
+|---|---|---|
+| `approval_ttl` | `7.days` | How long a parked approval (or in-doubt invocation) waits before expiring. Parked-forever ghosts are a bug, not a feature. |
+| `ask_question` | `true` | The built-in tool that parks the turn to ask the operator something. **Toggling it changes the definitions digest** — settle parked turns before flipping, or they fail loudly on resume (the nondeterminism guard working as designed). |
+
+## Memory
+
+| Option | Default | Meaning |
+|---|---|---|
+| `memory` | `true` | `false` removes the memory tools entirely (digest note above applies). |
+| `memory_approval` | `:always` | Every `remember` parks a card for a human; `:never` auto-approves. |
+| `memory_injection_limit` | `8` | How many recent memories are injected into each turn; `recall` digs deeper on demand. |
+
+## Inbox (`/silas/inbox`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `inbox_auth` | deny (404) | The lambda DENIES by rendering (or `head`-ing) and PASSES by not rendering — Devise-compatible: `->(controller) { controller.head :not_found unless controller.current_user&.admin? }`. |
+| `inbox_public_read` | `false` | Read-only for anyone; approve/decline/answer stay gated. |
+| `inbox_actor` | `current_user&.email \|\| "inbox"` | Identity recorded on approvals/declines/answers made in the inbox. |
+| `inbox_streaming` | `nil` (auto) | Live Turbo updates when the host has `turbo-rails`; `false` forces the polling fallback. |
+| `model_prices` | `{}` | **Override** map for cost accounting: `{"model-id" => { in:, out: }}` in units per 1k tokens, 1e6 units = $1 (a $3/MTok rate is `3000`). Everything else prices from RubyLLM's registry. |
+
+## JSON API (`/silas/api/v1`)
+
+| Option | Default | Meaning |
+|---|---|---|
+| `api_auth` | deny (404) | Same contract as `inbox_auth`. |
+| `api_actor` | `"api"` | Identity recorded on approvals made through the API. |
+| `api_stream_poll_interval` | `0.5` | Seconds between SSE row polls. |
+| `api_stream_max_duration` | `300` | Seconds before an SSE stream closes itself (clients reconnect with `Last-Event-ID`); bounds thread hold. |
+
+## Channels
+
+| Option | Default | Meaning |
+|---|---|---|
+| `slack_signing_secret` / `slack_bot_token` | `credentials.silas.slack.*` | Explicit setters override the credentials path; `nil` disables Slack. |
+
+## Evals
+
+| Option | Default | Meaning |
+|---|---|---|
+| `eval_dir` | `"test/agent_evals"` | Where `*_eval.rb` scenarios live (`bin/rails silas:eval`). |
+| `eval_grader` | `nil` | Custom LLM grader for `assert_rubric`; offline, rubric asserts skip rather than fail. |
+
+## Sandbox
+
+| Option | Default | Meaning |
+|---|---|---|
+| `sandbox` | `:none` | Code execution off. `:docker` (interim), or any object responding to `#run` — e.g. `Hermetic.gvisor(image: "python:3.12-slim")`. Configuring one advertises the `run_code` tool automatically. |
+| `sandbox_image` / `sandbox_network` / `sandbox_memory` / `sandbox_cpus` / `sandbox_pids` / `sandbox_workdir` / `sandbox_docker_bin` / `sandbox_timeout` | `nil` / `"none"` / `"512m"` / `"1"` / `256` / `"/workspace"` / `"docker"` / `30` | Docker knobs; inert unless `sandbox = :docker`. |
+
+## MCP & testing seams
+
+| Option | Default | Meaning |
+|---|---|---|
+| `mcp_server_host` | `"127.0.0.1"` | Bind host for the in-process MCP server (serving *your* tools to MCP clients). |
+| `mcp_client_factory` | `nil` | `->(connection) { client }` — inject a fake MCP client per connection in tests. |
+
+The remaining accessors (`tool_resolver`, `tool_definitions`,
+`definitions_digest`, `skills`, `schedules`, `subagent_*`,
+`named_agent_scopes`, `channel_resolver`, `instructions_dir`,
+`agent_override`) are internal wiring seams the Registry fills at boot — test
+hooks, not app configuration.
+
+## Boot guards (fail-loud misconfiguration)
+
+Two checks run at boot and **raise in production**, warn in development:
+
+- **No provider key configured** while `adapter = :ruby_llm` — the most common
+  first-run failure, surfaced at boot with the fix instead of dying inside the
+  first turn.
+- **ActiveJob on the in-process `:async` adapter** — it runs a re-enqueued
+  continuation concurrently with the original, double-executing steps and
+  voiding exactly-once. Use Solid Queue (production) or `:inline`
+  (scripts/demos). `bin/rails silas:doctor` checks both, everywhere.

data/docs/connections.md

@@ -0,0 +1,55 @@
+# Connections
+
+A connection plugs a remote MCP server's tools into your agent the same way
+everything else plugs in: **one data-only file, identity = filename.**
+
+```yaml
+# app/agent/connections/crm.yml
+url: https://mcp.example-crm.com/mcp
+auth:
+  type: bearer                     # or `header` with a `header:` name, or omit
+  credential: crm.mcp_token        # a PATH into Rails credentials — never the secret
+approval: once                     # never (default) | once | always
+effect: at_most_once               # at_most_once (default) | idempotent
+```
+
+Restart, and the server's tools appear to the model namespaced
+`crm__search`, `crm__create_note`, … — alongside your local tools, running
+through the same Ledger.
+
+## The rules the file encodes
+
+- **Credentials are paths, not secrets.** `credential: crm.mcp_token` resolves
+  `Rails.application.credentials.dig(:crm, :mcp_token)` at call time. The YAML
+  is committable; a missing credential fails loudly with the path named.
+- **Approval and effect mode are per-connection**, enforced by the same Ledger
+  as local tools. `approval: always` parks every remote call for a human;
+  `once` approves an identical (tool, arguments) pair once per session.
+- **`transactional!` does not exist here, by design.** A remote call can't
+  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).
+- **Transport is HTTP** (v1). Filename is the namespace: `crm.yml` →
+  `crm__*`.
+
+## Boot-time discovery, fail-loud
+
+Each connection's tool list is fetched **once at boot** and cached
+(`tools/list`). A misconfigured or unreachable connection raises **at boot**,
+never inside a turn — the same posture as the Registry's tool validation. The
+remote tool names and schemas are model-visible state, so they're part of the
+definitions digest: if the remote server changes its toolset, parked turns
+from before the change fail loudly on resume (`NondeterminismError`) instead
+of resuming against a different toolset. Settle parked turns before pointing a
+connection at a changed server.
+
+## Testing
+
+`config.mcp_client_factory = ->(connection) { fake_client }` injects a fake
+client per connection — the seam the gem's own specs use.
+
+## The other direction
+
+Silas can also *serve* your agent's tools as an MCP server (`Silas::Mcp::Server`,
+bound to `config.mcp_server_host`) — the "mount your tools as MCP" seam, so
+other MCP clients can call the tools you wrote for your agent.

data/docs/conventions.md

@@ -0,0 +1,161 @@
+# Conventions and deliberate deviations
+
+Silas follows Rails conventions by default. Where it doesn't, that's a
+decision, and this page records the reasoning so the next reader doesn't have
+to guess (or "fix" something load-bearing).
+
+Style is [`rubocop-rails-omakase`](https://github.com/rails/rubocop-rails-omakase)
+— Rails' own baseline, unmodified except for excluding the generated skeleton
+apps (`chaos_host/`, `examples/`, `spec/dummy/`). CI enforces RuboCop,
+Brakeman, bundler-audit, a Zeitwerk eager-load check, and a 90% line-coverage
+floor.
+
+## Naming and structure
+
+### `Adapters::`, not `Engines::`
+
+The pluggable inference backend lives at `Silas::Adapters::Base` /
+`Silas::Adapters::RubyLLM`, configured with `config.adapter`. It was called
+`Engines::` until 0.4, which collided with `Silas::Engine` — the Rails engine
+— in the same namespace. Every comparable seam disambiguates the same way:
+ActiveJob has `QueueAdapters::`, ActiveStorage has `Service::`, RubyLLM has
+`Provider`. The old constants and `config.engine` still work with a
+deprecation warning until 2.0.
+
+### `class << self` vs `module_function`
+
+Both appear, by rule, not by accident (the same split RubyLLM uses):
+
+- **`module_function`** for pure utility modules whose methods are all
+  legitimately callable — `Budget`, `MessageBuilder`, `Instructions`, `Inbox`,
+  `Slack`, `StepRunner`.
+- **`class << self` + `private`** where a module has real internals worth
+  hiding — `Ledger` (`execute!`, `claim!`, `guarded_transaction` are not
+  public API) — or holds state, like `Eval`'s scenario registry.
+
+`module_function` publishes every method on the module, so it is the wrong
+tool wherever encapsulation matters. Don't "unify" these.
+
+### Instrumentation
+
+Every notable moment in the durable loop emits an `ActiveSupport::Notifications`
+event named `<event>.silas` — the Rails convention (`sql.active_record`), so
+`subscribe(/\.silas\z/)` catches everything. `Silas::LogSubscriber` turns them
+into log lines at levels an operator can filter on: parks and rescues INFO,
+budget breaches WARN, failed turns and nondeterminism ERROR, per-step and
+per-token chatter DEBUG.
+
+Payloads always carry `turn_id`/`session_id` where they exist, so a subscriber
+never has to join. The full event list lives in `lib/silas/instrumentation.rb`;
+`tool.silas` (duration + effect_mode + how it settled) is the single most
+useful span, and `resume.silas` carries `parked_for` — how long the human took.
+
+Event names and payload keys are a public contract: dashboards get built on
+them, so renaming one is a breaking change, and `spec/silas/instrumentation_spec.rb`
+pins them.
+
+### Generator templates are `.rb.tt`
+
+Rails' own convention. A template containing ERB is not valid Ruby, so a bare
+`.rb` extension puts it in front of RuboCop's parser and Zeitwerk's loader —
+both of which are right to complain. `.tt` keeps them out of each. The install
+generator's templates predate this and are plain `.rb` because none of them
+interpolate; new templates use `.tt`.
+
+### Channels ship a generator, not a catalogue
+
+The engine serves webhook routes for Slack alone, because Slack is the only
+transport whose whole dialect Silas ships (signature scheme, Block Kit
+approvals, the interactive-actions endpoint). Every other transport is scaffolded
+into the *host* app by `rails g silas:channel`, since only the host knows the
+vendor's signature scheme and payload shape — and a framework promising to keep
+six drifting vendor APIs working is a framework that breaks.
+
+What that seam does own, because getting it wrong is a security bug rather than
+a preference: `Silas::Webhook.verify_hmac` (constant-time compare, replay
+window, fail-closed on a missing secret) and `Silas::Channel.approval_url` (a
+signed expiring link, host required and never guessed). See `docs/channels.md`.
+
+### The inbox speaks "Signals"; the API speaks database strings
+
+The inbox is themed dark-first (direction "Signals": one white "lamp" accent
+that never means state, plus an aspect colour per run state), and two states
+are relabelled **in the UI only**: `waiting` renders as **held**, `completed`
+as **clear** (`TraceHelper::UI_LABEL`). The database strings and the JSON API
+are untouched — an operator who reads "held" in the inbox and greps the API
+will find `waiting`, and both names appear in the docs for exactly that
+reason. Approval and question cards are hoisted to the top of a session (the
+trace keeps a one-line stub); the hoisted card's DOM id is
+`dom_id(invocation, :approval)` — distinct from the trace row's
+`dom_id(invocation)` — so Turbo can replace each independently.
+
+### Deprecations
+
+Everything removable goes through `Silas.deprecator`
+(`ActiveSupport::Deprecation`, registered in `app.deprecators[:silas]`), so a
+host silences or raises on Silas deprecations exactly as it does Rails'.
+Messages name the replacement *and* the removal version; a warning you can't
+act on is noise.
+
+## Deliberate deviations
+
+### Status columns are strings with constants, not Rails enums
+
+`Turn::STATUSES`, `ToolInvocation::STATUSES`, `Step` states and
+`approval_state` are validated strings.
+
+Enums generate scopes and predicate methods on the model, and the ledger
+performs its compare-and-swap claims through `update_all(status: "completed")`
+at the SQL level — where an enum's integer/string mapping is one more thing
+between the code and what the database actually holds. For a state machine
+whose correctness *is* the product, the literal value in the column being the
+literal value in the code is worth more than the generated sugar.
+
+### Webhook controllers skip CSRF
+
+`Silas::Channels::BaseController` calls `skip_forgery_protection`. No browser
+session originates a webhook, so no CSRF token can exist. Each route
+authenticates the request itself instead:
+
+- Slack routes verify an HMAC-SHA256 signature with a 300-second replay window.
+- Email approve/decline routes require a purpose-scoped, expiring
+  `MessageVerifier` token; possession of the token *is* the credential, so CSRF
+  would add nothing an attacker holding it couldn't already do.
+
+Both are covered by request specs including the negative cases (unsigned,
+wrong secret, stale, tampered, expired, wrong-purpose, replayed). The
+suppression is recorded with this reasoning in `config/brakeman.ignore`. The
+inbox controllers keep `protect_from_forgery`; the JSON API is
+`ActionController::API` and is token-authenticated.
+
+### Nothing is mass-assigned
+
+There is no `Model.new(params)` or `update(params)` anywhere, and therefore no
+strong-parameters ceremony. Every controller reads scalars explicitly
+(`params[:input].to_s.strip`) and passes them as keyword arguments. The one
+bulk value — a session's `metadata` hash on the JSON API — is assigned
+explicitly to a single JSON column, so it cannot reach any other attribute.
+
+### Indexes cover query paths, not every foreign key
+
+`silas_memories.session_id`, `turn_id` and `superseded_by_id` are provenance
+columns: written, never used in a `WHERE`. `silas_turns.job_id` is
+observability. They are deliberately unindexed — an index nobody reads is a
+write cost on the durable loop's hot path. The columns that *are* queried are
+indexed, including the partial unique index on `silas_turns` that enforces
+one active turn per session.
+
+## Conventions worth knowing
+
+- **Escaping**: no `raw`, `html_safe`, or `<%==` anywhere. Tool arguments,
+  tool results, and model output are rendered escaped, because a framework
+  that displays LLM and third-party output is the last place to hand-wave XSS.
+- **Time**: `Time.current`/`Time.zone` throughout; no `Time.now` or
+  `Date.today`.
+- **Concerns** live in `app/models/concerns/silas/`; the engine is
+  `isolate_namespace Silas` so host apps can't collide with it.
+- **Trace partials** are rendered in two contexts (the inbox controllers and
+  Turbo's broadcast jobs, which use the *host's* renderer). They therefore
+  build engine routes through `silas_engine_path`, never bare route helpers,
+  and the shared helper is registered host-wide. See
+  `spec/silas/inbox/broadcasting_spec.rb`.