silas 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f722788fa436905b6ea94ee9666ca71013fa6eace683f7d3dc8eec4f257fbe2
-  data.tar.gz: 85d3ae116127d4b91207526d7936440092250854380938a94eba177cd26f3eeb
+  metadata.gz: fd68f6d368466b20fbb35f49628f166ac61dd60ace3a8cbd20bbc6e316c1d346
+  data.tar.gz: 94d2a902cd7f364aa33200b1ea1f98446dabee38d9e9f7431df9cd96d1fc7f41
 SHA512:
-  metadata.gz: 645b843c5dbde892fa0725c1f33302bf39b3b10eef43ff14b0828efeb0420ead72d82e34b9bb3828cf99aa8f880db4f6017f2913023884a679385ca68a21ae41
-  data.tar.gz: 2b5b8df36d8747fde43b1eccffb466f17a3a9ef430ebc77b055b36c73ff987c4e07c66eb14ef2265d34b37b1ff824cf4681737a2bca1333e4e7dad88c8db142b
+  metadata.gz: c386608b076c2c3dfb23e369c819a7d7b1c4fc6122f0011ea80880a46b158b25549a75388a17de250b200a60e0ada311a73df28b47c67e4007cc9e2ebef8bf3f
+  data.tar.gz: 4216b83c6925605076cb3742286699673e2a18dfd9eab3a3cc6e21479ee64e17de714737e5764acce0f147ca0023ced60ed0864b0836850c771dbab88ea84100

data/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.6.0 (2026-07-26)
+
+The brand release: the Signals inbox, the docs surface (site + gem-shipped
+guides + tutorial), the templates family (desk + analyst) with its anti-rot
+CI gate, community files, and the framework-first README.
+
+### Added
+
+- **Docs for the whole surface.** New guides, all shipped in the gem:
+  `tutorial` (build the refund desk outward, one primitive per chapter),
+  `guarantees`, `tools`, `agents`, `memory`, `inbox-and-api`, `sandbox`,
+  `evals`, `budgets`, `cancellation`, `connections`, and a full
+  `configuration` reference. A docs site (Jekyll + just-the-docs, dark-first,
+  Archivo/Space Mono, `early · 0.x` chip) builds from `docs/` in CI and
+  deploys to Pages, with an `llms.txt` for coding agents. Brand assets
+  (`brand/`, hero at `docs/img/`) now live in the repo; the hero image is
+  excluded from the packaged gem.
+- **Rails application templates, as a family** — `templates/desk.rb` and
+  `templates/analyst.rb`, each a single CI-gated `rails new -m` script.
+  `rails new desk -m
+  https://raw.githubusercontent.com/danielstpaul/silas/main/templates/desk.rb`
+  builds a deployable agent app from nothing: a refund desk with one tool per effect
+  mode (`lookup_order` idempotent, `issue_refund` transactional behind a
+  £25 approval gate, `notify_customer` at-most-once), Solid Queue **and** Solid
+  Cable wired in development (the durability contract needs a real worker; live
+  deltas need a cross-process cable), a keyless scripted stand-in so the first
+  `bin/dev` works with zero secrets, three deterministic agent evals asserting
+  the hold and the exactly-once execution, and a Signals-branded signal-board
+  landing page. The template only runs the generators the gem already tests,
+  and the `templates_smoke` workflow regenerates and tests an app from every
+  template on each push — starters that structurally cannot rot. (eve needs
+  template repos because it has no generator story; Rails has application
+  templates.) **The analyst** is the second template: a scheduled reporting
+  agent — `query_metrics` reads, `flag_anomaly` lands rows exactly once,
+  `publish_report` holds at the signal (`approval :always`), a Monday-07:00
+  schedule, and a schema-checked `final_answer` (`Turn#answer_data`). Both
+  templates also wire `ANTHROPIC_API_KEY` into Kamal's secrets so the
+  generated app deploys without a scavenger hunt.
+- **Community files** — `CONTRIBUTING.md` (the deliberate scope no-list, the
+  chaos-gate requirement, how templates are contributed), `SECURITY.md`
+  (private vulnerability reporting; deny-by-default surfaces; contract
+  violations count), and GitHub issue forms.
+- **The gem ships its own docs, and the installer ships a coding-agent skill.**
+  `docs/**` and `DEPLOY.md` are in the packaged gem, so `bundle show silas`
+  gives a coding agent (or an offline human) the real reference — and the
+  README's links stop 404ing for gem-only readers. `rails g silas:install` now
+  also writes `.claude/skills/silas/SKILL.md`: the `app/agent/` conventions,
+  the effect-mode and approval decision rules, and the ledger rules an agent
+  must never violate — so a Claude Code/Codex session building on this app
+  gets the framework's judgment without the human learning it first. Gemspec
+  gains `documentation_uri` and `bug_tracker_uri`.
+
+### Changed
+
+- **The inbox wears the brand** (direction "Signals"). Dark-first — the tokens'
+  base is the night palette and light is the `prefers-color-scheme` override —
+  with a position-light mark, a lowercase wordmark, and one white "lamp" accent
+  that never means state. The seven run states each get their aspect:
+  `in_doubt` its own violet (it is neither waiting-by-design nor failed),
+  `canceled` a dashed quiet (a lamp going out, not turning red), and two
+  UI-only relabels — `waiting` reads **held**, `completed` reads **clear**. The
+  database strings and the JSON API are untouched (`docs/conventions.md`).
+- **Approvals and questions are hoisted to the top of the session** — the
+  operator never scrolls a long trace hunting for the card; the trace keeps a
+  one-line "held at the signal" stub in place. Live parks append their card via
+  the same Turbo broadcasts; settled cards remove themselves. Tool arguments
+  render as key/value rows and results collapse behind a disclosure; the
+  session index groups its rail by who's blocked: **Held / Working / Filed**.
+- The playground's chat page consumes the engine's colour tokens instead of
+  re-hardcoding a palette, and hosts the hoisted approval/question cards above
+  its transcript.
+
+- **README reframed, framework-first** — it now mirrors eve's shape exactly:
+  the mark as the logo (dark/light `<picture>`), badges, a one-paragraph
+  thesis, "The filesystem is the authoring interface" with the tree, quick
+  start, one minimal example, status/community/license. The hero illustration
+  moved to the repo's social-preview role (its inbox panel is a designed
+  idealization, not a screenshot — it shouldn't sit where users compare it to
+  the real `/silas/inbox`). The docs site nav is grouped eve-style — Tutorial
+  and Guarantees up top, then **Core / Advanced / Reference / About**
+  sections — via build-time frontmatter injection (`site/assemble.rb`, which
+  fails the build if a docs page lacks a nav entry), keeping the gem-shipped
+  markdown frontmatter-free. `docs/vs-eve.md` was **factually rewritten**
+  (2026-07-26): the previous revision described eve as a managed-cloud
+  platform; eve is fully self-hostable, and the comparison now rests on what's
+  actually different — exactly-once vs documented at-least-once, a shipped
+  production inbox vs a dev TUI, memory vs none, and the transaction-boundary
+  argument, date-stamped against eve 0.27.6 and framed as siblings (pick by
+  stack). `docs/why-silas.md` rewritten in the same voice — you build the same
+  things with Silas you'd build with any modern agent framework; the
+  guarantees are where it goes further — and DEPLOY.md dropped its stale "eve
+  without the bill" subtitle.
+
+### Fixed
+
+- The generated `config/initializers/ruby_llm.rb` no longer guards its whole
+  configure block behind `ANTHROPIC_API_KEY` — keyless boots skipped the
+  `use_new_acts_as` opt-in, so every demo-mode boot printed RubyLLM's legacy
+  acts_as deprecation warning. A nil key assignment is inert; the block now
+  always runs.
+
 ## 0.5.0 (2026-07-26)
 
 Two new loop primitives (replay-safe compaction, ask_question), a whole-channel

data/DEPLOY.md

@@ -0,0 +1,111 @@
+# Deploying Silas
+
+A Silas app is an ordinary Rails app, so it deploys the way your Rails apps
+already deploy — a single cheap VPS with Kamal works fine; there is no second
+runtime or control plane to stand up. The one thing you MUST get right: the
+**Solid Queue worker has to run**, because the durability contract (a turn
+surviving a crash / deploy) depends on it. A web-only deploy will accept turns
+and never run them.
+
+> Status: this is the reference configuration. It is correct by construction
+> (worker wired, rescuer active, secrets injected) but has not yet been run
+> against a live VPS end-to-end — that's the final launch step.
+
+## 1. The worker must run
+
+> **Queue adapter: use Solid Queue.** Silas's durability and exactly-once
+> guarantees require a durable, serializing, DB-backed adapter. **Do not run on
+> the in-process `:async` adapter** (Rails' development default) — it runs
+> continuation retries on a thread pool concurrently with the original job,
+> which double-executes steps and breaks exactly-once. Silas warns at boot if it
+> detects the Async adapter. For scripts and single-process demos, the
+> synchronous `:inline` adapter is safe (but has no durability).
+
+`rails g silas:install` already appends the durability rescuer to
+`config/recurring.yml`:
+
+```yaml
+production:
+  silas_dead_job_rescuer:      # retries jobs failed by dead-worker reaping/pruning
+    class: Silas::DeadJobRescuerJob
+    schedule: every 30 seconds
+```
+
+Pick one way to run Solid Queue:
+
+- **Simple (one container):** run the worker inside Puma —
+  set `SOLID_QUEUE_IN_PUMA=true` (Rails 8 default plugin). Fine for a demo box.
+- **Recommended (durable):** a dedicated `bin/jobs` process, so a `kill -9` of the
+  worker is isolated from the web tier and recovery is observable.
+
+## 2. Kamal config (`config/deploy.yml`)
+
+A standard `rails new` ships a Dockerfile and `config/deploy.yml`. Add a **job
+role** so the worker is its own container:
+
+```yaml
+service: my-agent
+image: you/my-agent
+servers:
+  web:
+    - 1.2.3.4          # your £5/month VPS
+  job:
+    hosts:
+      - 1.2.3.4
+    cmd: bin/jobs      # the Solid Queue worker (+ dispatcher + scheduler)
+
+registry:
+  username: you
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+env:
+  secret:
+    - RAILS_MASTER_KEY
+    - ANTHROPIC_API_KEY        # the :ruby_llm engine authenticates with this
+  clear:
+    SOLID_QUEUE_IN_PUMA: false # the job role runs the worker instead
+
+# Persist SQLite + Solid Queue on a volume if you're using SQLite (or point at Postgres).
+volumes:
+  - "my_agent_storage:/rails/storage"
+```
+
+Secrets (Slack signing secret / bot token, model keys) go in `.kamal/secrets`
+(pulled from your env or a vault), never in the image.
+
+## 3. Deploy
+
+```sh
+kamal setup     # first time
+kamal deploy    # subsequent
+```
+
+Mid-deploy safety is built in: a turn interrupted by the SIGTERM of a rolling
+deploy re-enqueues and resumes (chaos-gated). Recovery latency after a hard
+crash ≈ `SolidQueue.process_alive_threshold` + the rescuer's 30s cadence.
+
+## 3½. Template apps deploy stock
+
+An app generated from `templates/*.rb` needs no deploy surgery: Rails 8.1's
+generated `config/deploy.yml` already runs Solid Queue inside Puma for the
+single-server SQLite shape (`SOLID_QUEUE_IN_PUMA: true` — that satisfies "the
+worker must run"), the template adds `ANTHROPIC_API_KEY` to Kamal's secret
+list and `.kamal/secrets`, and `config/recurring.yml` already carries the
+rescuer. Set the two secrets in your shell, point `deploy.yml` at your server
+and registry, `kamal setup`. Scale beyond one box by moving to the dedicated
+worker role in §1 and a real Postgres in §2.
+
+## 4. Cost
+
+The whole thing runs on one VPS + your model spend. The engine authenticates
+with an API key for whatever provider you configure through RubyLLM. Your data
+and the ledger never leave your own Postgres, and there is no Silas platform
+bill or per-run metering.
+
+## 5. Local development note (macOS + Postgres)
+
+Solid Queue forks workers, and on macOS the pg gem needs
+`PGGSSENCMODE=disable OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES` in the
+environment or forked workers crash inside libpq. SQLite development needs
+nothing.

data/README.md

@@ -1,295 +1,126 @@
-# Your Rails app is already an agent runtime.
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/danielstpaul/silas/main/brand/silas-wordmark.svg">
+    <img src="https://raw.githubusercontent.com/danielstpaul/silas/main/brand/silas-wordmark-light.svg" alt="silas" width="150">
+  </picture>
+</p>
 
-**Silas** turns the Rails app you already run into a durable AI-agent runtime.
-Active Job Continuations, Solid Queue, and one Postgres ledger table make every
-turn survive `kill -9` and resume from the last completed step — with a live
-operator inbox at `/silas/inbox` and park-at-zero human-in-the-loop approvals
-holding the big levers. No new service, no managed platform, no per-run meter:
-the durable stack is already booted inside your app. The only new surface is the
-`app/agent/` directory below.
+<p align="center">
+  <a href="https://rubygems.org/gems/silas"><img src="https://img.shields.io/gem/v/silas" alt="Gem"></a>
+  <a href="https://github.com/danielstpaul/silas/actions/workflows/ci.yml"><img src="https://github.com/danielstpaul/silas/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/danielstpaul/silas/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
 
-Honestly early and honestly narrow: **v0.1, one maintainer, zero external
-users**, durability proven by an in-repo `kill -9` chaos harness (100/100, zero
-duplicate effects, byte-identical replay), and scoped to **trusted code you write
-yourself** by default — for untrusted or model-generated code, drop in the
-companion gem [hermetic](https://github.com/danielstpaul/hermetic) (gVisor /
-Firecracker / hosted sandboxes behind one call, see below). The full pitch
-and the honest caveats: [Why Silas](docs/why-silas.md) ·
-[Silas vs eve](docs/vs-eve.md).
+Silas is a Rails-native framework for durable AI agents. An agent's
+capabilities live as plain files in conventional locations inside the app you
+already run — easy to inspect, extend, and operate — and its tool effects
+land **exactly once**, even through a crash.
+
+## The filesystem is the authoring interface
+
+A typical Silas agent:
 
 ```
 app/agent/
-  instructions.md   # the persona (ERB, snapshotted once per turn)
-  agent.yml         # data-only config: model, limits
-  tools/            # one file per tool; identity = filename
-    issue_refund.rb #   keyword signature = the schema the model sees
+  instructions.md   # the persona
+  agent.yml         # model + limits — data only
+  tools/            # one file per tool; filename = identity, keywords = schema
   skills/           # markdown playbooks, loaded on demand
-    triage.md       #   description: frontmatter is the routing hint
-```
-
-## Quickstart
-
-```sh
-bundle add silas
-bin/rails generate silas:install
-bin/rails db:migrate
-bin/rails silas:doctor   # key · queue adapter · model · migrations · tools · rescuer · cable · auth
+  schedules/        # cron frontmatter -> recurring turns
+  channels/         # slack.rb, email.rb — transports bound to the loop
+  connections/      # remote MCP servers as <name>.yml
 ```
 
-```ruby
-class Agent::Tools::IssueRefund < Silas::Tool
-  description "Refund an order."
-  param :amount, :integer, desc: "Pence"
-  approval :always      # parks the run; a human approves from your app
-  transactional!        # DB-only side effects -> exactly-once, guaranteed
+Documentation lives at
+**[danielstpaul.github.io/silas](https://danielstpaul.github.io/silas)** —
+start with the [tutorial](https://danielstpaul.github.io/silas/tutorial). The
+same docs ship inside the gem (`bundle show silas`), and the installer writes
+a Claude Code skill so coding agents working in your app know the conventions.
 
-  def call(order_id:, amount:)
-    Refund.create!(order_id:, amount:)
-    { refunded: order_id }
-  end
-end
-```
+## Quick start
 
-```ruby
-session = Silas.agent.start(input: "Refund order 42, £12.50")
-session.pending_approvals.first.approve!(by: "daniel")
-session.continue(input: "Now email the customer.")
+```bash
+rails new my-agent -m https://raw.githubusercontent.com/danielstpaul/silas/main/templates/desk.rb
 ```
 
-Or talk to it from the terminal — the REPL runs *inside your app*, so tools hit
-your real dev database, and parked approvals prompt inline (the same
-`approve!`/`decline!` as the inbox and Slack):
+This creates a new agent app with Solid Queue wired, a starter refund-desk
+agent installed, and a keyless demo — the first `cd my-agent && bin/dev`
+needs no API key. More starting shapes live in
+[templates/](https://github.com/danielstpaul/silas/tree/main/templates) —
+swap `desk.rb` for `analyst.rb` to start from a scheduled reporting agent
+instead.
 
-```
-$ bin/rails silas:chat
-you> Refund order 42, £12.50
-  ✓ lookup_order(order_id: 42)
-  ⏸ issue_refund(order_id: 42, amount: 1250) — awaiting approval
+To add Silas to an existing app:
 
-approval needed — issue_refund(order_id: 42, amount: 1250)
-approve? [y]es / [d]ecline / [s]kip> y
-agent> Done — £12.50 refunded on order 42.
+```bash
+bundle add silas
+bin/rails generate silas:install
+bin/rails db:migrate
 ```
 
-`SESSION=id` resumes an existing session.
+`bin/rails silas:doctor` verifies the whole setup.
 
-## The durability contract (what's actually guaranteed)
+## A minimal example
 
-Verified by `chaos_host/bin/chaos` — the harness that kill -9s a live agent
-hundreds of times per release (results in `chaos_host/results/`):
+Replace `app/agent/instructions.md` with your agent's persona:
 
-- **A turn survives hard process death** (worker kill -9, whole-tree kill -9,
-  SIGTERM deploys) and resumes from the last completed step: 100% completion,
-  byte-identical transcripts, on SQLite and Postgres.
-- **`transactional!` tools execute exactly once.** The tool's DB writes and the
-  ledger row commit or roll back together. Zero duplicates across every chaos run.
-- **Other tools are at-least-once within one step** — and when a crash makes an
-  execution ambiguous, the default `at_most_once!` policy **parks the run for a
-  human verdict** instead of guessing (`idempotent!` opts into automatic re-runs).
-- **Approvals park at zero compute** — the job exits; approving enqueues a fresh
-  one that replays completed work from rows, never re-calling the model or
-  re-running tools. Parks expire (default 7 days) rather than ghosting forever.
-- **Transient model errors retry from the checkpoint.** A rate limit,
-  overload, or timeout backs off and retries the job — and the continuation
-  resumes from the last completed step, never re-running completed work.
-  Exhausted retries and permanent rejections (bad key, bad request) expire
-  pending approvals and fail the turn loudly. **A turn can never sit in
-  `running` forever**: the rescuer also fails turns stranded by a loop job
-  that died outside the retry list.
-- **The rescuer is part of the contract.** Solid Queue marks a dead worker's
-  jobs failed and nothing retries them; the installer wires
-  `Silas::DeadJobRescuerJob` as a recurring task (every 30s). Recovery time ≈
-  `SolidQueue.process_alive_threshold` + that cadence. Do not remove it.
-- **Deploys can't corrupt a run**: instructions are snapshotted per turn, and a
-  deploy that changes tools/skills mid-turn fails the turn loudly
-  (`NondeterminismError`) instead of resuming into a different agent.
-
-## Adapter
-
-Inference is one pluggable seam (`config.adapter`): `:ruby_llm` — API-key auth
-via [RubyLLM](https://rubyllm.com), any provider it supports — is the default
-and the production path. Compose resilience via `config.around_model_call`, or
-swap in any object responding to `#execute_step` (the eval harness and the
-chaos tests do exactly that).
-
-> The experimental `:agent_sdk` adapter (a `claude -p` subprocess) was removed
-> in 0.2: its subscription-auth rationale was structurally unreachable, and it
-> carried weaker guarantees than `:ruby_llm` on every axis. Its in-process MCP
-> server survives and returns as a first-class *mount your tools as MCP*
-> feature.
-
-## Sandbox: run untrusted code with hermetic
+```markdown
+You are the refund desk. Look orders up before promising anything, and never
+quote an amount a tool didn't return.
+```
 
-The sandbox is a second pluggable seam (`config.sandbox`). Built-in adapters are
-`:none` (default — code execution off) and `:docker` (hardened container,
-honest-but-interim). For real isolation, the companion gem
-[**hermetic**](https://github.com/danielstpaul/hermetic) drops straight in:
+Create a tool at `app/agent/tools/issue_refund.rb` — the keyword signature
+*is* the schema the model sees:
 
 ```ruby
-# Gemfile: gem "hermetic"   (zero runtime deps)
-Silas.configure do |c|
-  c.sandbox = Hermetic.gvisor(image: "python:3.12-slim")     # or .docker /
-  # .firecracker(kernel:, rootfs:) / .hosted(:e2b, api_key:) # pick your strength
+class Agent::Tools::IssueRefund < Silas::Tool
+  description "Refund part or all of an order."
+  approval ->(session:, input:) { input[:amount_pence] > 2_500 ? :user_approval : :approved }
+  transactional!   # DB effect + ledger commit atomically -> exactly-once
+
+  def call(number:, amount_pence:, reason:)
+    order = Order.find_by!(number: number)
+    refund = order.refunds.create!(amount_pence:, reason:)
+    { refunded_pence: refund.amount_pence, order: order.number }
+  end
 end
 ```
 
-That's the whole integration. When a sandbox is configured and enabled, the
-`run_code` tool is advertised to the model automatically (`at_most_once!` — an
-exec is an external effect). Two properties carry through the seam:
-
-- **The trust axis is visible**: every hermetic backend exposes `trust`
-  (`:vendor`/`:remote`/`:vm`/`:host`) and `off_host?`, so you can refuse to run
-  untrusted code on the box that holds your `RAILS_MASTER_KEY` — pair any local
-  backend with `executor:` to push execution to a dedicated sandbox host.
-- **The ledger guard is auto-armed**: configuring a hermetic backend loads its
-  Silas shim, so a sandbox exec attempted inside a ledger transaction fails loud
-  (sandbox-backed tools must be `at_most_once!`, never `transactional!`).
-
-## Named agents: the staff pattern
-
-One app can employ several agents, each with its own room:
-
-```
-app/agents/
-  reader/            # Silas.agent(:reader).start(input: "...")
-    instructions.md
-    agent.yml        # model, limits — same keys as the root agent
-    tools/
-    skills/
-  clerk/
-    ...
-```
-
-Sessions are stamped with the agent's name; every turn — including crash
-resumes — runs under that agent's own tools, skills, instructions, and
-definitions digest. The inbox filters by agent; `bin/rails silas:chat
-AGENT=clerk` chats with one staff member. The root `app/agent/` remains the
-default agent, unchanged. (Subagents stay a root-agent delegation feature;
-scope switching is execution-isolated, so concurrent jobs running different
-agents never cross wires.)
-
-## Memory & handoffs
-
-Silas memory is **graph-shaped, not a graph database**: facts as
-`subject · attribute · content` triples with provenance and supersession
-("author:jane · report_format: prefers CSV" — a new value retires the old).
-The `remember` tool is **approval-gated by default** — the memory card parks
-in your inbox before anything persists; `recall` digs deeper than the few
-recent memories injected into each turn. Private per agent, or `shared: true`
-for the whole staff. Your *domain* data does not belong here — it belongs in
-your own tables, which your tools already read; memory is for the fuzzy
-residue with no natural home.
-
-Staff compose through **handoffs, not conversations**: `handoff` files a
-self-contained brief that starts a linked session for another named agent
-(async, or `await: true` for an answer), exactly-once-guarded, cycle-checked.
-Two models chatting freely is a cost and audit hazard — deliberately
-unblessed.
-
-## Triggers
+Restart, then talk to it:
 
-An agent is reached by more than a method call:
-
-- **`schedules/`** — `app/agent/schedules/*.md` (cron frontmatter, body = the turn
-  input) or `*.rb` handlers. `bin/rails silas:schedules` compiles them into
-  Solid Queue recurring tasks. A scheduled run is a normal durable turn. Named
-  agents own their cron the same way they own tools:
-  `app/agents/analyst/schedules/monday_kpis.md` ticks start the analyst, not
-  the root agent.
-- **`channels/`** — `app/agent/channels/*.rb` bind email (Action Mailbox) and
-  Slack to the loop. A new thread starts a session, a reply continues it, and
-  approvals render as Slack buttons / signed email links that call the same
-  `approve!`/`decline!`. Outbound delivery is idempotent and off the durable loop.
-  `bin/rails g silas:channel whatsapp` scaffolds any other transport — a
-  signature-verifying webhook and the outbound half, wired together. See
-  [docs/channels.md](https://github.com/danielstpaul/silas/blob/main/docs/channels.md).
-
-## Streaming
-
-Turns stream. The `:ruby_llm` adapter emits text deltas as the model responds:
-`bin/rails silas:chat` prints tokens as they arrive, and the inbox trace
-renders them live over Turbo (coalesced to ~10Hz). Deltas are decoration over
-the durable rows — never persisted, never fed back to the model, and a
-replayed step renders from its row with no deltas at all, so streaming adds
-zero risk to the durability contract. Custom sinks subscribe to the
-`"delta.silas"` notification (`{ session_id:, turn_id:, step_id:, step_index:,
-text: }`, where `text` is the accumulated string so far — filter by ids;
-notifications are process-global).
-
-## Structured answers
-
-Give the turn's final answer a schema in agent.yml and read it back as a Hash:
-
-```yaml
-final_answer:
-  type: object
-  properties:
-    verdict: { type: string }
-    amount_pence: { type: integer }
-  required: [verdict]
+```bash
+bin/rails silas:chat
 ```
 
-`Turn#answer_data` returns the parsed payload (`answer_text` stays for prose
-agents); the HTTP API carries it as `answer_data`, evals get
-`assert_answer_data(key: :verdict, value: "approve")`. Rendered through
-RubyLLM's `with_schema`, so each provider's native structured-output mode is
-used. The schema is model-visible state — changing it mid-turn fails the turn
-loudly rather than resuming into a different contract.
+Refunds over £25 hold for a person — in the operator inbox the gem mounts at
+`/silas/inbox`, in Slack, or over the JSON API — and approving resumes the
+turn exactly where it stopped, with exactly one refund row in your database.
+How that's guaranteed (and verified with a `kill -9` chaos harness on every
+release): [guarantees](https://danielstpaul.github.io/silas/guarantees).
 
-## The HTTP API
+## Status
 
-Everything the operator surface can do, over JSON — mounted with the engine at
-`/silas/api/v1`, **deny-by-default** like the inbox (wire `config.api_auth`;
-`config.api_actor` names the identity recorded on approvals):
+Early (0.5.x) and moving fast. Requires Rails >= 8.1 (Active Job
+Continuations) and Solid Queue >= 1.2; any model provider
+[RubyLLM](https://rubyllm.com) supports.
 
-```sh
-curl -X POST .../silas/api/v1/sessions -d "input=Refund order 42, £12.50"
-curl .../silas/api/v1/sessions/1?trace=1                # turns + steps + tool calls
-curl .../silas/api/v1/sessions/1/approvals              # what's parked
-curl -X POST .../silas/api/v1/approvals/7/approve       # the same approve! as the inbox
-curl -X POST .../silas/api/v1/sessions/1/turns -d "input=Now email them"   # 409 if busy
-curl -X POST .../silas/api/v1/turns/9/cancel
-curl -N .../silas/api/v1/sessions/1/stream              # server-sent events
-```
-
-The stream is SSE at **row granularity** — turn / completed-step / invocation
-changes, at-least-once with `Last-Event-ID` resume (ids are epoch-ms
-watermarks; `?poll=1` returns the backlog and closes, curl-friendly; streams
-close themselves after `api_stream_max_duration` and clients reconnect).
-Per-token streaming is deliberately the browser/Turbo feature — deltas live in
-the worker process, and the gem requires no cross-process bus.
-
-## The inbox
+## Community
 
-Mount the engine (the generator does this) and a live inbox appears at
-`/silas/inbox`: a session list, **web chat** (start a session or reply from
-the browser — same durable loop, no separate surface), a live step-trace that
-streams tokens over Turbo Streams as the agent runs, approval cards whose
-Approve/Decline buttons call the exact same `approve!`/`decline!` as Slack and
-email, a full **audit trail** (every tool call's arguments and its result or
-recorded error; who approved; who declined and why), **cancel** on active
-turns (honored at the next step boundary), and per-session token/cost
-accounting. It's **deny-by-default** — invisible until you wire auth:
+Questions, ideas, and bug reports →
+[issues](https://github.com/danielstpaul/silas/issues).
 
-```ruby
-Silas.configure do |c|
-  # Devise-compatible: the lambda DENIES by rendering; passes by not rendering.
-  c.inbox_auth = ->(controller) { controller.head :not_found unless controller.current_user&.admin? }
-  # c.inbox_public_read = true   # public read-only demo; approve/decline stay gated
-  # c.model_prices["your-model"] = { in: 300, out: 1500 }  # microcents / 1k tokens
-end
-```
+## Contributing
 
-Turbo streaming activates automatically when the host has `turbo-rails` (every
-default Rails app does); without it the trace falls back to a polling refresh.
-The gem itself takes no turbo dependency.
+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.
 
-## Requirements
+## Security
 
-Rails >= 8.1 (Active Job Continuations) and Solid Queue >= 1.2 for the
-durability contract. macOS dev note: Solid Queue forks + pg need
-`PGGSSENCMODE=disable OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES`.
+Please report vulnerabilities privately via
+[GitHub's vulnerability reporting](https://github.com/danielstpaul/silas/security/advisories/new)
+— see [SECURITY.md](https://github.com/danielstpaul/silas/blob/main/SECURITY.md).
 
 ## License
 
-MIT.
+[MIT](https://github.com/danielstpaul/silas/blob/main/LICENSE).