docs: rewrite README.md from shared SDK template

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nficano

README.md

@@ -1,135 +1,287 @@
-# arcp
+<h3 align="center">ARCP Ruby SDK</h3>
 
-Ruby SDK for ARCP v1. The wire protocol is specified in
-[the ARCP spec](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md). This
-gem implements the full v1 envelope, session handshake, job lifecycle,
-event stream, leases, and error model.
+<p align="center"><strong>Ruby SDK for the Agent Runtime Control Protocol (ARCP) — submit, observe, and control long-running agent jobs from Ruby.</strong></p>
 
-## Install
+<p align="center">
+  <a href="https://rubygems.org/gems/arcp"><img alt="gem" src="https://img.shields.io/gem/v/arcp.svg"></a>
+  <a href="https://github.com/nficano/arpc/actions/workflows/test.yml"><img alt="CI" src="https://github.com/nficano/arpc/actions/workflows/test.yml/badge.svg"></a>
+  <a href="https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md"><img alt="ARCP" src="https://img.shields.io/badge/ARCP-v1.1%20draft-blue"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-lightgrey"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md">Specification</a> ·
+  <a href="#concepts">Concepts</a> ·
+  <a href="#installation">Install</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="docs/">Guides</a> ·
+  <a href="docs/api/">API reference</a>
+</p>
+
+---
+
+`arcp` is the Ruby reference implementation of [ARCP](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md), the Agent Runtime Control Protocol. It covers both sides of the wire — `Arcp::Client` for submitting and observing jobs, `Arcp::Runtime::Runtime` for hosting agents — so either side can talk to any conformant peer in any language without hand-rolling the envelope, sequencing, or lease enforcement.
+
+ARCP itself is a transport-agnostic wire protocol for long-running AI agent jobs. It owns the parts of agent infrastructure that don't change between products — sessions, durable event streams, capability leases, budgets, resume — and stays out of the parts that do. ARCP wraps the agent function; it does not define how agents are built, how tools are exposed (that's MCP), or how telemetry is exported (that's OpenTelemetry).
+
+## Installation
+
+Requires Ruby 3.3 or later. The gem runs on the `socketry/async` reactor and pulls in `async-websocket` for the default networked transport and `sqlite3` for the resume log; no separate extras are needed. Add it to a `Gemfile`:
 
 ```ruby
 gem 'arcp', '~> 1.0'
 ```
 
-Requires Ruby 3.3+. Runs on the `socketry/async` reactor; pairs with
-`falcon` for hosting and `async-websocket` for the WebSocket transport.
+```sh
+bundle install
+```
+
+## Quick start
 
-## Quickstart
+Connect to a runtime, submit a job, stream its events to completion:
 
 ```ruby
 require 'async'
 require 'arcp'
 
+ECHO = lambda do |ctx|
+  ctx.log(level: 'info', message: "echoing #{ctx.input.inspect}")
+  ctx.progress(current: 1, total: 1, units: 'message')
+  ctx.finish(result: { 'echoed' => ctx.input })
+end
+
 Sync do
   runtime = Arcp::Runtime::Runtime.new(
     auth_verifier: Arcp::Auth::Bearer.from_token('demo', principal_id: 'alice'),
     heartbeat_interval_sec: nil
   )
-  runtime.register_agent(
-    name: 'echo', versions: ['1.0.0'], default: '1.0.0',
-    handler: ->(ctx) {
-      ctx.progress(current: 1, total: 1, units: 'message')
-      ctx.finish(result: { 'echoed' => ctx.input })
-    }
-  )
+  runtime.register_agent(name: 'echo', versions: ['1.0.0'], default: '1.0.0', handler: ECHO)
 
   server_t, client_t = Arcp::Transport::MemoryTransport.pair
   server = Async { runtime.accept(server_t) }
 
   client = Arcp::Client.open(
     transport: client_t,
-    auth: { 'scheme' => 'bearer', 'token' => 'demo' }
+    auth: { 'scheme' => 'bearer', 'token' => 'demo' },
+    client_name: 'quickstart'
   )
+
   handle = client.submit_job(agent: 'echo', input: { 'msg' => 'hi' })
-  handle.subscribe(client: client).each { |ev| puts ev.kind }
-  puts handle.get_result(client: client).result.inspect
+  handle.subscribe(client: client).each { |event| puts "#{event.kind}: #{event.body.to_h}" }
+  result = handle.get_result(client: client)
+  puts "final: #{result.final_status} #{result.result.inspect}"
 
   client.close
   server.stop
 end
 ```
 
-## What is ARCP
+This is the whole shape of the SDK: open a session, submit work, consume an ordered event stream, get a terminal result or error. Everything below is detail on those four moves.
+
+## Concepts
+
+ARCP organizes everything around four concerns — **identity**, **durability**, **authority**, and **observability** — expressed through five core objects:
+
+- **Session** — a connection between a client and a runtime. A session carries identity (a bearer token), negotiates a feature set in a `hello`/`welcome` handshake, and is *resumable*: if the transport drops, you reconnect with a resume token and the runtime replays buffered events. Jobs outlive the session that started them. See [§6](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
+- **Job** — one unit of agent work submitted into a session. A job has an identity, an optional idempotency key, a resolved agent version, and a lifecycle that ends in exactly one terminal state: `success`, `error`, `cancelled`, or `timed_out`. See [§7](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
+- **Event** — the ordered, session-scoped stream a job emits: logs, thoughts, tool calls and results, status, metrics, artifact references, progress, and streamed result chunks. Events carry strictly monotonic sequence numbers so the stream survives reconnects gap-free. See [§8](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
+- **Lease** — the authority a job runs under, expressed as capability grants (`fs.read`, `fs.write`, `net.fetch`, `tool.call`, `agent.delegate`, `cost.budget`, `model.use`). The runtime enforces the lease at every operation boundary; a job can never act outside it. Leases may carry a budget and an expiry, and may be subset and handed to sub-agents via delegation. See [§9](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
+- **Subscription** — read-only attachment to a job started elsewhere (e.g. a dashboard watching a job a CLI submitted). A subscriber observes the live event stream but cannot cancel or mutate the job. Distinct from *resume*, which continues the original session and carries cancel authority. See [§7.6](https://github.com/agentruntimecontrolprotocol/spec/blob/main/docs/draft-arcp-1.1.md).
+
+The SDK models each of these as first-class objects; the rest of this README shows how.
 
-ARCP is a session-oriented protocol for invoking remote agents. A client
-opens a session, submits jobs, and receives a stream of structured events
-followed by a terminal result or error. The protocol covers capability
-negotiation, heartbeats, ordered acks, cursored job listing, cross-session
-observation, capability-bounded leases, and trace propagation.
+## Guides
+
+### Sessions and resume
+
+Open a session, negotiate features, and reconnect transparently after a transport drop using the resume token — jobs keep running server-side while you're gone.
+
+```ruby
+require 'async'
+require 'arcp'
+
+Sync do
+  client = Arcp::Client.open(
+    transport: transport,
+    auth: { 'scheme' => 'bearer', 'token' => ENV.fetch('ARCP_TOKEN') },
+    client_name: 'resumable'
+  )
+
+  session_id   = client.session.id
+  resume_token = client.session.resume_token
+  last_seq     = Hash.new(0)
+  handle = client.submit_job(agent: 'long-runner')
+  handle.subscribe(client: client).each do |event|
+    last_seq[handle.job_id] = event.body.respond_to?(:seq) ? event.body.seq : last_seq[handle.job_id]
+  end
+
+  # ... transport drops ...
+
+  resumed = Arcp::Client.open(
+    transport: new_transport,
+    auth: { 'scheme' => 'bearer', 'token' => ENV.fetch('ARCP_TOKEN') },
+    resume: { 'token' => resume_token, 'last_event_seq' => last_seq }
+  )
+  # The runtime replays every event with event_seq > last_seq, then resumes live streaming.
+end
+```
 
-## Features
+### Submitting jobs
 
-- Capability negotiation (§6.2)
-- Heartbeat / ping-pong (§6.4)
-- Application-level ack (§6.5)
-- Cursored `list_jobs` (§6.6)
-- Cross-session `job.subscribe` with history replay (§7.6)
-- Agent versioning with `name@version` refs (§7.5)
-- `result_chunk` streaming with result_id terminator (§8.4)
-- `progress` events (§8.2)
-- `lease_constraints.expires_at` (§9)
-- `cost.budget` capability with `BigDecimal` arithmetic (§9.6)
-- Resume token + last_event_seq replay (§6.3)
-- Trace context propagation (§11)
+Submit a job with an agent (optionally version-pinned as `name@version`), an input, and an optional lease request, idempotency key, and runtime limit.
 
-## Architecture
+```ruby
+handle = client.submit_job(
+  agent: 'weekly-report@2.1.0',
+  input: { 'week' => '2026-W19' },
+  lease_request: Arcp::Lease::LeaseRequest.new(
+    capabilities: ['net.fetch'],
+    expires_at: (Time.now.utc + 60).iso8601
+  ),
+  lease_constraints: Arcp::Lease::LeaseConstraints.new(
+    expires_at: (Time.now.utc + 300).iso8601,
+    max_budget: nil
+  ),
+  idempotency_key: 'weekly-report-2026-W19',
+  max_runtime_sec: 300
+)
 
+puts "job_id           = #{handle.job_id}"
+puts "resolved agent   = #{handle.agent.inspect}"
+puts "effective lease  = #{handle.lease&.to_h.inspect}"
 ```
-Arcp::Client            # session-oriented client
-Arcp::Runtime::Runtime  # server-side runtime; accepts transports
-Arcp::Runtime::JobContext # passed to agent handlers
-Arcp::Session::*        # Hello, Welcome, CapabilitySet, Feature, AgentInventory, ...
-Arcp::Job::*            # Submit, Accepted, Event, Result, JobError, Handle, Summary
-Arcp::Job::EventKind    # 10 standard kinds
-Arcp::Lease::*          # Lease, LeaseRequest, LeaseConstraints, CostBudget, Subsetting
-Arcp::Transport::*      # MemoryTransport, WebSocketTransport, StdioTransport
-Arcp::Auth::*           # AuthScheme, Bearer, Principal
-Arcp::Errors::*         # 15 wire codes + 3 internal-only
-Arcp::Trace             # Fiber-local Context, span helpers
+
+### Consuming events
+
+Iterate the ordered event stream — `log`, `thought`, `tool_call`, `tool_result`, `status`, `metric`, `artifact_ref`, `progress`, `result_chunk` — and optionally acknowledge progress so the runtime can release buffered events early.
+
+```ruby
+last_seq = 0
+handle.subscribe(client: client).each do |event|
+  case event.kind
+  when Arcp::Job::EventKind::LOG
+    puts event.body.message
+  when Arcp::Job::EventKind::TOOL_CALL
+    puts "-> tool #{event.body.name}(#{event.body.arguments.inspect})"
+  when Arcp::Job::EventKind::METRIC
+    puts "metric #{event.body.name}=#{event.body.value}#{event.body.unit}"
+  when Arcp::Job::EventKind::PROGRESS
+    puts "progress #{event.body.current}/#{event.body.total} #{event.body.units}"
+  end
+  last_seq += 1
+  client.ack(last_seq) if (last_seq % 32).zero?  # coalesced session.ack
+end
 ```
 
-## Transports
+### Leases and budgets
 
-- `Arcp::Transport::MemoryTransport.pair` — in-process queue pair. Tests, embedded clients.
-- `Arcp::Transport::WebSocketTransport` — wraps an `Async::WebSocket::Connection`. Production transport.
-- `Arcp::Transport::StdioTransport` — newline-delimited JSON over a pair of IOs. Co-process agents.
+Request capabilities, a budget, and an expiry; read budget-remaining metrics as they arrive; handle the runtime's enforcement decisions.
 
-## Deployment
+```ruby
+handle = client.submit_job(
+  agent: 'web-research',
+  input: { 'iterations' => 8 },
+  lease_request: Arcp::Lease::LeaseRequest.new(
+    capabilities: ['tool.call', 'cost.spend'],
+    budget: Arcp::Lease::CostBudget.parse(['USD:1.00']),
+    expires_at: (Time.now.utc + 600).iso8601
+  )
+)
 
-Run the runtime as a daemon under the `socketry/async` reactor. Host
-WebSocket endpoints with `falcon`. The runtime is fiber-based and
-multiplexes sessions on the reactor; do not deploy under
-request-per-thread servers like Puma.
+puts "initial budget = #{handle.lease&.budget&.to_a.inspect}"
 
-## Errors
+handle.subscribe(client: client).each do |event|
+  next unless event.kind == Arcp::Job::EventKind::METRIC
+  next unless event.body.name == 'cost.budget.remaining'
 
-15 wire codes, each mapped to an `Arcp::Errors::*` subclass with a
-`retryable?` default: `Cancelled`, `InvalidRequest`, `Unauthenticated`,
-`PermissionDenied`, `JobNotFound`, `AgentNotAvailable`, `DuplicateKey`,
-`RateLimited`, `Internal`, `HeartbeatLost`, `Backpressure`,
-`ProtocolViolation`, `Timeout`, `ResumeWindowExpired`,
-`LeaseSubsetViolation`, `AgentVersionNotAvailable`, `LeaseExpired`,
-`BudgetExhausted`. Three additional codes are library-internal and never
-appear on the wire (`UNNEGOTIATED_FEATURE`, plus the abstract
-`Arcp::Error` base and the generic `Internal` fallback).
+  puts "budget remaining: #{event.body.value} #{event.body.unit}"
+end
 
-## Documentation
+begin
+  handle.get_result(client: client)
+rescue Arcp::Errors::BudgetExhausted, Arcp::Errors::LeaseExpired => e
+  # Never retryable — resubmit with a fresh lease/budget instead.
+  warn "job ended: #{e.code} #{e.message}"
+end
+```
 
-See `docs/` for guides, concepts, and reference. Start with
-`docs/getting-started.md`.
+### Subscribing to jobs
 
-## Conformance
+Attach read-only to a job submitted elsewhere and observe its live stream (with optional history replay) without cancel authority.
+
+```ruby
+Sync do
+  observer = Arcp::Client.open(
+    transport: dashboard_transport,
+    auth: { 'scheme' => 'bearer', 'token' => ENV.fetch('ARCP_TOKEN') },
+    client_name: 'dashboard'
+  )
 
-Spec-to-code matrix in [CONFORMANCE.md](CONFORMANCE.md).
+  running = observer.list_jobs(status: 'running', limit: 1).first
+  stream  = observer.subscribe_job(job_id: running.job_id, from_event_seq: 0, history: true)
 
-## Development
+  stream.each do |event|
+    puts "[#{running.job_id}] #{event.kind}"
+  end
 
+  observer.close
+end
 ```
-bundle install
-bundle exec rake          # spec + rubocop + steep
-bundle exec rake docs     # build doc tree
+
+### Error handling
+
+Catch the typed error taxonomy and respect the `retryable` flag — `LEASE_EXPIRED` and `BUDGET_EXHAUSTED` are never retryable; a naive retry fails identically.
+
+```ruby
+begin
+  handle = client.submit_job(agent: 'flaky', input: {})
+  handle.get_result(client: client)
+rescue Arcp::Errors::LeaseExpired, Arcp::Errors::BudgetExhausted => e
+  raise e  # resubmit with a fresh lease / budget instead
+rescue Arcp::Error => e
+  if e.retryable?
+    # safe to retry with backoff (e.g. INTERNAL_ERROR, RATE_LIMITED, TIMEOUT)
+    retry_with_backoff(e)
+  else
+    raise
+  end
+end
 ```
 
+## Feature support
+
+ARCP features this SDK negotiates during the `hello`/`welcome` handshake:
+
+| Feature flag | Status |
+|---|---|
+| `heartbeat` | Supported |
+| `ack` | Supported |
+| `list_jobs` | Supported |
+| `subscribe` | Supported |
+| `lease_expires_at` | Supported |
+| `cost.budget` | Supported |
+| `model.use` | Supported |
+| `provisioned_credentials` | Supported |
+| `progress` | Supported |
+| `result_chunk` | Supported |
+| `agent_versions` | Supported |
+
+## Transport
+
+ARCP is transport-agnostic. This SDK ships a WebSocket transport (default), a stdio transport for in-process child runtimes, and an in-memory transport for tests. WebSocket is the default for networked runtimes; stdio is used for in-process child runtimes. Select one by constructing the corresponding transport object and passing it to `Arcp::Client.open(transport:, ...)`: `Arcp::Transport::WebSocketTransport.new(connection: ws)` for production (wrap an open `Async::WebSocket::Connection`, typically hosted under `falcon`), `Arcp::Transport::StdioTransport` for co-process agents, or `Arcp::Transport::MemoryTransport.pair` for in-process tests and embedded clients.
+
+## API reference
+
+Full API reference — every type, method, and event payload — is in [`docs/`](docs/) (YARD-generated reference under [`docs/api/`](docs/api/), rebuilt with `bundle exec rake docs`).
+
+## Versioning and compatibility
+
+This SDK speaks **ARCP v1.1 (draft)**. The SDK follows semantic versioning independently of the protocol; the protocol version it negotiates is shown above and in `session.hello`. A runtime advertising a different ARCP MAJOR is not guaranteed compatible. Feature mismatches degrade gracefully: the effective feature set is the intersection of what the client and runtime advertise, and the SDK will not use a feature outside it.
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md). Protocol questions and proposed changes belong in the [spec repository](https://github.com/agentruntimecontrolprotocol/spec); SDK bugs and feature requests belong here.
+
 ## License
 
-Apache-2.0. See `LICENSE`.
+Apache-2.0 — see [`LICENSE`](LICENSE).