docs: align documentation with actual SDK surface

Reviewed every doc against the source under src/ and corrected the
fictional or stale API claims that had accumulated:

- Project docs (Cli, AspNetCore, Giraffe, Otel, Client, Core, Arcp)
  rewritten to match the real exported types and helpers.
- Guides (sessions, auth, resume, jobs, job-events, errors,
  vendor-extensions, observability) updated for the actual
  ArcpClientOptions, JobHandle, ITransport, ToolOutcome, and Features
  shapes; removed the imagined envelope `extensions` block.
- Reference docs (architecture, getting-started, transports, cli,
  troubleshooting, recipes) updated for the real CLI commands and
  transport constructors.

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

Author: Nick Ficano

docs/README.md

@@ -42,5 +42,5 @@
 - [Recipes](recipes.md) — common patterns
 - [Conformance](conformance.md) — spec coverage summary
 - [Troubleshooting](troubleshooting.md) — common errors and fixes
-- [Diagrams](diagrams/README.md) — Graphviz sources and rendered SVGs
+- [Diagrams](diagrams/README.md) — Graphviz sources and rendered SVGs (`architecture-light.dot`, `architecture-dark.dot`)
 - [Root conformance document](../CONFORMANCE.md)

docs/architecture.md

@@ -29,19 +29,20 @@ The shared kernel — no client/runtime distinction, no I/O. Exports:
 - **`Envelope`** — eight-field wire record. `arcp = "1.1"`.
   `Payload : JsonElement` is kept lazy so decoders only pay for what
   they read.
-- **`Message` DU** — one case per protocol message type. Every `match`
-  is compile-checked; adding a new type is a compile error until all
-  match arms are updated.
+- **`Message` DU** — eighteen cases, one per protocol message type.
+  Every `match` is compile-checked; adding a new type is a compile
+  error until all match arms are updated.
 - **`ARCPError` DU** — exhaustive 15-case discriminated union for all
   spec error codes. No stringly-typed error handling.
 - **`LeaseGrant`** — `Map<namespace, glob list>`; stateless
   `validateLeaseOp` runs glob match → expiry → budget in that order.
-- **`Features`** — `Set<string>` of feature flag names; `Features.All`
-  is the canonical SDK default.
+- **`Features`** — string constants plus `Features.All : Set<string>`;
+  the canonical SDK default is the full set.
 - **Codec** — `Codec.toEnvelope`, `Codec.toMessage`,
   `Codec.readEnvelope`, `Codec.writeEnvelope`. Uses
-  `FSharp.SystemTextJson` with `JsonUnionEncoding.InternalTag` so the
-  discriminator `type` field sits at the same level as peer fields.
+  `FSharp.SystemTextJson` (`WithUnionExternalTag()` keyed on `"type"`,
+  `WithUnionUnwrapRecordCases()`) so the discriminator sits at the same
+  level as peer fields.
 
 See [Arcp.Core](projects/Arcp.Core.md).
 
@@ -57,11 +58,13 @@ the handshake, dispatches inbound envelopes, and exposes:
   terminal envelope.
 - `SubscribeAsync(jobId, opts, ct)` — attaches to an in-progress job
   from another session (requires `subscribe` feature).
-- `ListJobsAsync(filter, ct)` — paginated job listing (requires
-  `list_jobs` feature).
+- `UnsubscribeAsync(jobId, ct)` — stop receiving events for a
+  subscribed job.
+- `ListJobsAsync(filter, limit, cursor, ct)` — paginated job listing
+  (requires `list_jobs` feature).
 - `AckAsync(seq, ct)` — explicit ack for back-pressure (requires `ack`
-  feature).
-- `CloseAsync(ct)` — graceful session teardown.
+  feature). Auto-ack runs in the background once `ack` is negotiated.
+- `CloseAsync(reason, ct)` — graceful session teardown via `session.bye`.
 
 Transports: `MemoryTransport`, `StdioTransport`,
 `WebSocketClientTransport`. See [transports.md](transports.md).
@@ -81,13 +84,15 @@ server.SetDefaultAgentVersion("hello", "2.0")
 server.HandleSessionAsync(transport, ct) // runs one session
 ```
 
-`JobContext` is the agent's window into the runtime. It emits all
-eight reserved event kinds (`EmitLogAsync`, `EmitThoughtAsync`,
-`EmitToolCallAsync`, `EmitToolResultAsync`, `EmitStatusAsync`,
-`EmitProgressAsync`, `EmitMetricAsync`, `EmitArtifactRefAsync`),
-exposes `Lease`, `LeaseConstraints`, and `CancellationToken`, and
-provides v1.1 streaming via `BeginStreamingResult()` /
-`EmitResultChunkAsync`.
+`JobContext` is the agent's window into the runtime. It emits every
+reserved event kind (`EmitLogAsync`, `EmitThoughtAsync`,
+`EmitStatusAsync`, `EmitProgressAsync`, `EmitToolCallAsync`,
+`EmitToolResultAsync`, `EmitMetricAsync`, `EmitArtifactRefAsync`,
+`EmitDelegateAsync`) plus `EmitVendorEventAsync` for the `x-vendor.*`
+namespace, exposes `Lease`, `LeaseConstraints`, `Credentials`,
+`RemainingBudget`, and `CancellationToken`, and provides v1.1
+streaming via `BeginStreamingResult()` / `EmitResultChunkAsync`.
+Lease enforcement runs through `ValidateOpAsync`.
 
 `type ArcpAgentHandler = JobContext -> Task<JsonElement>`
 
@@ -104,11 +109,14 @@ See [Arcp.AspNetCore](projects/Arcp.AspNetCore.md) and
 
 ## `Arcp.Otel`
 
-Provides `ArcpActivitySource.Instance` (the shared `ActivitySource`)
-and `ArcpSpanAttributes` constants (`arcp.session_id`, `arcp.job_id`,
-`arcp.agent`, `arcp.lease.capabilities`, `arcp.lease.expires_at`,
-`arcp.budget.remaining`). Your instrumentation code uses these
-constants to attach well-known attributes to spans.
+Provides `ArcpActivitySource.Instance` (the shared `ActivitySource`,
+name `"ARCP"`), `ArcpSpanAttributes` constants (`arcp.session_id`,
+`arcp.job_id`, `arcp.agent`, `arcp.lease.capabilities`,
+`arcp.lease.expires_at`, `arcp.budget.remaining`), and two `ArcpOtel`
+helpers (`beginJobSpan`, `recordBudgetRemaining`) for runtime
+implementers who want to wrap a job in an `Activity`. Trace context is
+carried as the envelope's top-level `trace_id` field — no
+`extensions` block is emitted by this SDK.
 
 See [Arcp.Otel](projects/Arcp.Otel.md).
 
@@ -120,7 +128,7 @@ Every message is one JSON object with eight top-level fields:
 | ------------ | ------------------------------------------- | -------------------------------------------- |
 | `arcp`       | always                                      | `"1.1"` (the protocol version literal)       |
 | `id`         | always                                      | ULID or UUIDv7, unique per message           |
-| `type`       | always                                      | discriminator (`"session.hello"`, `"job.submit"`, …) |
+| `type`       | always                                      | discriminator (`"session.hello"`, `"job.submit"`, ...) |
 | `payload`    | always                                      | type-specific body; decoded lazily           |
 | `session_id` | after handshake                             | absent on pre-session frames                 |
 | `job_id`     | job-scoped envelopes                        | set on `job.*` types                         |

docs/cli.md

@@ -9,18 +9,21 @@ dotnet tool install --global --add-source ./artifacts Arcp.Cli
 
 ## `arcp serve`
 
-Start a runtime listening on stdio:
+Start a runtime listening on stdio. A single `echo` agent is registered;
+it is intended as a smoke-test runtime, not a production binary.
 
 ```
-arcp serve [--stdio] [--token TOKEN]
+arcp serve [--stdio | -s] [--token TOKEN]
 ```
 
-| Option    | Default         | Notes                                                   |
-| --------- | --------------- | ------------------------------------------------------- |
-| `--stdio` | always set      | Only stdio transport is supported in v1.                |
-| `--token` | `$ARCP_TOKEN`   | Bearer token. Falls back to the `ARCP_TOKEN` env var. If neither is set, a dev-mode verifier is used that accepts any token. |
+| Option    | Default     | Notes                                                                                                            |
+| --------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--stdio` | (implied)   | Only stdio is supported; the flag is reserved for future transports.                                             |
+| `--token` | dev mode    | When set, only this exact bearer token is accepted (`StaticBearerVerifier`). When unset and `$ARCP_TOKEN` is empty, a permissive dev-mode verifier accepts any non-empty token. |
 
-Example — spawn a runtime as a child process with a fixed token:
+`ARCP_TOKEN` is consulted only when `--token` is omitted.
+
+Example — run with a fixed token:
 
 ```bash
 ARCP_TOKEN=secret arcp serve --stdio
@@ -44,8 +47,10 @@ arcp send --url URL --agent AGENT [--token TOKEN] [--input JSON]
 | `--token` | no       | Bearer token. Falls back to `$ARCP_TOKEN`.                     |
 | `--input` | no       | JSON-encoded input. Defaults to `null`.                        |
 
-Events are printed to stdout as they arrive. On completion the final
-result or error is printed and the process exits.
+Each received event prints one `event: <kind>` line to stdout. On a
+`job.result` the inline result (or the literal `null`) is printed and
+the process exits with code 0; on a `job.error` the error code and
+message are written to stderr and the process exits with code 1.
 
 ```bash
 arcp send \
@@ -60,9 +65,14 @@ arcp send \
 Prints the SDK version and the ARCP protocol version it targets:
 
 ```
-arcp --version
+$ arcp --version
+arcp 1.0.0 (protocol 1.1)
 ```
 
+There is no `arcp cancel`, `arcp status`, `arcp events`, or `arcp ls` —
+the CLI is intentionally tiny. Drive those operations from a script
+that uses `ArcpClient` directly.
+
 ## Samples
 
 ```bash

docs/getting-started.md

@@ -35,7 +35,7 @@ let server =
 
 server.RegisterAgent("echo", fun ctx ->
     task {
-        do! ctx.EmitStatusAsync("running", ctx.CancellationToken)
+        do! ctx.EmitStatusAsync("running", None, ctx.CancellationToken)
         do! ctx.EmitLogAsync(LogLevel.Info, "received", ctx.CancellationToken)
         return Json.serializeToElement<{| echoed: obj |}> {| echoed = ctx.Input |}
     })
@@ -62,8 +62,15 @@ let request : JobSubmitRequest = {
 }
 
 let handle = (client.SubmitAsync(request, CancellationToken.None)).Result
-let result = handle.Result.Result
-// → JsonElement: { "echoed": { "hi": 1 } }
+
+// handle.Result : Task<Result<JobResultPayload, ARCPError>>
+match handle.Result.Result with
+| Ok payload ->
+    payload.Result
+    |> Option.iter (fun el -> printfn "%s" (el.GetRawText()))
+    // → { "echoed": { "hi": 1 } }
+| Error err ->
+    eprintfn "[%s] %s" (ARCPError.code err) (ARCPError.message err)
 ```
 
 You should see two events (`status: running`, `log: info`) arriving before
@@ -82,15 +89,17 @@ using ARCP.Runtime;
 var server = new ArcpServer(ArcpServerOptions.defaults);
 server.RegisterAgent("echo", async ctx =>
 {
-    await ctx.EmitStatusAsync("running", ctx.CancellationToken);
+    await ctx.EmitStatusAsync("running", null, ctx.CancellationToken);
     await ctx.EmitLogAsync(LogLevel.Info, "received", ctx.CancellationToken);
     return JsonSerializer.SerializeToElement(new { echoed = ctx.Input });
 });
 
 var (clientT, serverT) = MemoryTransport.CreatePair();
 _ = server.HandleSessionAsync(serverT, CancellationToken.None);
 
-await using var client = new ArcpClient(
+// `ArcpClientOptions` is an F# record; from C# you build it with the
+// generated constructor, passing every field.
+using var client = new ArcpClient(
     clientT,
     new ArcpClientOptions(
         // "1.0" is this demo client's application version, not the ARCP protocol version.
@@ -129,12 +138,24 @@ app.MapArcp("/arcp", server) |> ignore
 app.Run("http://localhost:7878")
 ```
 
-On the client side use `WebSocketClientTransport`:
+On the client side use `WebSocketClientTransport.connectAsync`, which
+opens a `ClientWebSocket`, attaches the bearer token (if any) as an
+`Authorization` header on the upgrade, and returns an `ITransport`:
 
 ```fsharp
-let transport = new WebSocketClientTransport(uri) :> ITransport
-let client = new ArcpClient(transport, ArcpClientOptions.defaults)
-let _ = client.ConnectAsync(CancellationToken.None).Result
+open ARCP.Client.Transport
+
+task {
+    let! transport =
+        WebSocketClientTransport.connectAsync
+            (System.Uri "ws://localhost:7878/arcp")
+            (Some "demo")                       // bearer token, or None
+            CancellationToken.None
+
+    let client = new ArcpClient(transport, ArcpClientOptions.defaults)
+    let! _session = client.ConnectAsync CancellationToken.None
+    return client
+}
 ```
 
 ## Run over stdio

docs/guides/auth.md

@@ -30,22 +30,24 @@ let options =
 
 ### Dev-mode verifier (default)
 
-`ArcpServerOptions.defaults` includes a permissive verifier that
-accepts any non-empty token and maps it to a principal of `"dev"`. This
-is useful for local testing but must never be used in production.
+`ArcpServerOptions.defaults` wires in `DevModeBearerVerifier`, which
+accepts any non-empty token and maps it to a principal id of
+`"dev:<token>"`. This is useful for local testing but must never be
+used in production.
 
 ### Static verifier
 
-`StaticBearerVerifier` accepts a map of `token → principal`:
+`StaticBearerVerifier` accepts a `IReadOnlyDictionary<string, string>`
+of `token → principal-id`:
 
 ```fsharp
-open ARCP.Runtime
+open ARCP.Runtime.Auth
 
 let verifier =
     StaticBearerVerifier(
-        Map.ofList [
-            ("token-alice", "alice")
-            ("token-bob", "bob")
+        readOnlyDict [
+            "token-alice", "alice"
+            "token-bob",   "bob"
         ])
 
 let options =
@@ -57,27 +59,32 @@ let server = ArcpServer(options)
 ### Custom verifier
 
 Implement `IBearerVerifier` to add JWT validation, database lookups, or
-any other auth logic:
+any other auth logic. `VerifyAsync` returns
+`Task<Result<IPrincipal, ARCPError>>` — on rejection, supply the
+`ARCPError.Unauthenticated` case you want surfaced:
 
 ```fsharp
+open ARCP.Core
+open ARCP.Runtime.Auth
+
 type JwtVerifier(signingKey: string) =
     interface IBearerVerifier with
-        member _.VerifyAsync(token, ct) =
+        member _.VerifyAsync(token, _ct) =
             task {
-                let principal = validateJwt signingKey token
-                return
-                    if principal <> null then Some principal
-                    else None
+                match validateJwt signingKey token with
+                | Some claims -> return Ok(StringPrincipal(claims.Subject) :> IPrincipal)
+                | None -> return Error(ARCPError.Unauthenticated "Invalid bearer token")
             }
 
 let options =
     { ArcpServerOptions.defaults with
         BearerVerifier = JwtVerifier("my-secret") }
 ```
 
-`VerifyAsync` should return `Some principal` for a valid token, or
-`None` to reject. A rejected token causes the runtime to send
-`session.error` with `UNAUTHENTICATED` and close the transport.
+Returning `Error` causes the runtime to send `session.error` with
+`UNAUTHENTICATED` and close the transport. `StringPrincipal` lives in
+`ARCP.Runtime.Auth`; you can also implement `IPrincipal` directly to
+expose `Labels`.
 
 ## Wire shape
 
@@ -99,17 +106,25 @@ schemes requires explicit handling in a custom verifier.
 
 ## Vendor auth schemes
 
-The spec reserves `x-vendor.<vendor>.<scheme>` for custom auth. To
-accept vendor schemes, implement `IBearerVerifier` and inspect the
-raw `AuthPayload.Scheme` field:
+The spec reserves `x-vendor.<vendor>.<scheme>` for custom auth. The
+current SDK only passes the bearer `token` to the verifier — `Auth`'s
+raw `Scheme` field is consumed by the handshake before `VerifyAsync`
+is called and is not surfaced here. To support vendor schemes today,
+embed the scheme distinction inside the token itself and dispatch on
+it from a custom verifier:
 
 ```fsharp
+open ARCP.Core
+open ARCP.Runtime.Auth
+
 type MultiSchemeVerifier() =
     interface IBearerVerifier with
-        member _.VerifyAsync(token, ct) =
+        member _.VerifyAsync(token, _ct) =
             task {
-                // 'token' is the raw Auth.Token value; scheme is inspected upstream
-                return Some "any-principal"
+                if token.StartsWith("acme:") then
+                    return Ok(StringPrincipal(token.Substring 5) :> IPrincipal)
+                else
+                    return Error(ARCPError.Unauthenticated "Unknown auth scheme")
             }
 ```