docs: add 10 spec-aligned guides (closes #28 partially)

Author: nficano

docs/guides/auth.md

@@ -0,0 +1,91 @@
+# Authentication
+
+> Spec reference: ARCP v1.1 §6.1
+
+ARCP uses **bearer token authentication**. The client presents a token; the runtime maps it to a *principal* (a string identity). All authorization decisions use the principal.
+
+## Static bearer verifier
+
+For development and testing, use `StaticBearerVerifier` with a hard-coded token-to-principal map:
+
+```python
+from arcp.runtime import ARCPRuntime, RuntimeInfo, StaticBearerVerifier
+
+runtime = ARCPRuntime(
+    runtime=RuntimeInfo(name="my-service", version="1.0.0"),
+    bearer=StaticBearerVerifier({
+        "alice-token": "alice@example.com",
+        "bob-token": "bob@example.com",
+    }),
+)
+```
+
+## Custom verifier
+
+Implement the `BearerVerifier` protocol to integrate with any auth backend:
+
+```python
+from arcp.runtime import BearerVerifier
+
+class DatabaseVerifier:
+    """Look up tokens in a database."""
+
+    def __init__(self, db):
+        self._db = db
+
+    async def verify(self, token: str) -> str | None:
+        """Return the principal, or None to reject the token."""
+        row = await self._db.fetchone(
+            "SELECT principal FROM api_tokens WHERE token = $1 AND revoked = false",
+            token,
+        )
+        return row["principal"] if row else None
+
+runtime = ARCPRuntime(
+    runtime=RuntimeInfo(name="my-service", version="1.0.0"),
+    bearer=DatabaseVerifier(db),
+)
+```
+
+The `verify` method is called once per session, at connect time. Returning `None` causes the runtime to close the connection with `AuthenticationError`.
+
+## JWT verifier
+
+```python
+import jwt
+from arcp.runtime import BearerVerifier
+
+class JWTVerifier:
+    def __init__(self, secret: str):
+        self._secret = secret
+
+    async def verify(self, token: str) -> str | None:
+        try:
+            payload = jwt.decode(token, self._secret, algorithms=["HS256"])
+            return payload["sub"]
+        except jwt.InvalidTokenError:
+            return None
+```
+
+## Accessing the principal in an agent
+
+The session principal is available in the `JobContext`:
+
+```python
+async def my_agent(input, ctx):
+    principal = ctx.principal  # e.g. "alice@example.com"
+    if principal != "admin@example.com":
+        raise PermissionError("admin only")
+    return {"ok": True}
+```
+
+## Authorization
+
+ARCP handles *authentication* (who are you?). *Authorization* (what can you do?) is the application's responsibility. Use `ctx.principal` to make authorization decisions inside agent functions.
+
+## Related
+
+- [Sessions guide](sessions.md)
+- [Custom auth recipe](../recipes/custom-auth.md)
+- [Provisioned credentials recipe](../recipes/provisioned-credentials.md)
+- [Delegation guide](delegation.md)

docs/guides/delegation.md

@@ -0,0 +1,83 @@
+# Delegation
+
+> Spec reference: ARCP v1.1 §10
+
+**Delegation** allows an agent acting as a client to downstream runtimes to carry the original caller's identity. This creates a verifiable trust chain: the downstream runtime can see who originally initiated the work.
+
+## Basic pattern
+
+```
+Alice ──► Runtime A  ──►  Runtime B
+        (agent A)         (agent B)
+```
+
+Agent A on Runtime A submits a job to Runtime B. Runtime B sees Alice as the delegated principal, not agent A's service identity.
+
+## Creating a delegation token
+
+On Runtime A, inside the agent function:
+
+```python
+async def orchestrator(input, ctx):
+    # Create a scoped delegation token for the downstream call
+    token = ctx.create_delegation_token(
+        scopes=["summarise"],      # restrict to specific agents
+        expires_in_s=60,
+    )
+
+    # Connect to Runtime B with the delegation token
+    client_b = ARCPClient(
+        client=ClientInfo(name="orchestrator", version="1.0.0"),
+        token=token,
+    )
+    await client_b.connect(runtime_b_transport)
+
+    handle = await client_b.submit(agent="summarise", input=input)
+    result = await handle.done
+    await client_b.close()
+
+    return result.result
+```
+
+## Verifying delegation on Runtime B
+
+Runtime B automatically validates delegation tokens if configured with the same signing key:
+
+```python
+runtime_b = ARCPRuntime(
+    runtime=RuntimeInfo(name="runtime-b", version="1.0.0"),
+    bearer=StaticBearerVerifier({"service-token": "service@example.com"}),
+    delegation_secret="shared-signing-key",  # must match Runtime A
+)
+```
+
+Inside agent B, `ctx.principal` will be Alice's identity, and `ctx.delegated_by` will be the orchestrator's identity.
+
+```python
+async def summarise(input, ctx):
+    print(ctx.principal)       # "alice@example.com"
+    print(ctx.delegated_by)    # "orchestrator@service.example.com"
+    ...
+```
+
+## Delegation depth
+
+ARCP supports multi-hop delegation (A → B → C). Each hop appends to a delegation chain. The chain is validated at each runtime.
+
+## Restricting delegation scope
+
+```python
+token = ctx.create_delegation_token(
+    scopes=["summarise", "translate"],  # only these agents may be called
+    max_hops=2,                          # chain depth limit
+    expires_in_s=120,
+)
+```
+
+Attempting to call an out-of-scope agent raises `AuthorizationError`.
+
+## Related
+
+- [Auth guide](auth.md)
+- [Delegate recipe](../recipes/delegate.md)
+- [Multi-agent budget recipe](../recipes/multi-agent-budget.md)

docs/guides/errors.md

@@ -0,0 +1,101 @@
+# Errors
+
+> Spec reference: ARCP v1.1 §12
+
+All ARCP exceptions inherit from `ARCPError`. The 15 typed exceptions map 1:1 to spec §12 error codes and are importable from `arcp`.
+
+## Exception hierarchy
+
+```
+ARCPError
+├── AuthenticationError      (auth.failed)
+├── AuthorizationError       (auth.unauthorized)
+├── AgentNotFoundError       (agent.not_found)
+├── AgentVersionNotFoundError(agent.version_not_found)
+├── JobNotFoundError         (job.not_found)
+├── JobCancelledError        (job.cancelled)
+├── LeaseExceededError       (lease.exceeded)
+├── LeaseExpiredError        (lease.expired)
+├── LeaseDeniedError         (lease.denied)
+├── DelegationError          (delegation.invalid)
+├── ResumeError              (resume.invalid)
+├── CapabilityError          (capability.unsupported)
+├── RateLimitError           (rate_limit.exceeded)
+├── InternalError            (internal)
+└── ProtocolError            (protocol)
+```
+
+## Handling errors
+
+```python
+from arcp import (
+    ARCPError,
+    AuthenticationError,
+    LeaseExceededError,
+    JobCancelledError,
+    AgentNotFoundError,
+)
+
+try:
+    handle = await client.submit(agent="my-agent", input={"x": 1})
+    result = await handle.done
+except AuthenticationError:
+    # Token was rejected at session connect time
+    print("Check your bearer token")
+except AgentNotFoundError:
+    # Agent name not registered on the runtime
+    print("Agent not found")
+except LeaseExceededError as e:
+    # Job exceeded its cost or time budget
+    print(f"Budget exceeded: {e.code}")
+except JobCancelledError:
+    # Job was cancelled (by client or runtime)
+    print("Job was cancelled")
+except ARCPError as e:
+    # Catch-all for any other ARCP error
+    print(f"ARCP error: {e.code} — {e.message}")
+```
+
+## Error attributes
+
+Every `ARCPError` has:
+
+| Attribute | Type | Description |
+|---|---|---|
+| `code` | `str` | Spec error code, e.g. `"lease.exceeded"` |
+| `message` | `str` | Human-readable description |
+| `data` | `dict \| None` | Optional structured detail |
+
+## Raising errors from agents
+
+Agents can signal well-typed failures by raising `ARCPError` subclasses:
+
+```python
+from arcp import AuthorizationError
+
+async def admin_only(input, ctx):
+    if ctx.principal != "admin@example.com":
+        raise AuthorizationError("only admin can call this agent")
+    return {"secret": 42}
+```
+
+The runtime converts the exception into a `job.failed` event with the matching error code.
+
+## Catching errors inside agents
+
+Unhandled exceptions from agent functions are caught by the runtime and emitted as `job.failed` with `InternalError`. Catch expected exceptions explicitly:
+
+```python
+async def fragile_agent(input, ctx):
+    try:
+        result = await call_external_api(input)
+    except httpx.TimeoutException as e:
+        raise InternalError(f"external API timed out: {e}") from e
+    return result
+```
+
+## Related
+
+- [Troubleshooting](../troubleshooting.md)
+- [Leases guide](leases.md) — `LeaseExceededError`, `LeaseExpiredError`
+- [Auth guide](auth.md) — `AuthenticationError`, `AuthorizationError`

docs/guides/job-events.md

@@ -0,0 +1,95 @@
+# Job events
+
+> Spec reference: ARCP v1.1 §8
+
+While a job runs, the runtime emits a stream of **typed events**. Every event has a `kind` discriminator, a `seq` (monotonically increasing sequence number), and a `job_id`.
+
+## Event kinds
+
+| Kind | Trigger | Key fields |
+|---|---|---|
+| `job.queued` | Job accepted by runtime | `job_id`, `agent`, `seq` |
+| `job.started` | Agent function invoked | `job_id`, `resume_token`, `seq` |
+| `job.log` | `ctx.log(level, msg)` | `level`, `message`, `seq` |
+| `job.progress` | `ctx.progress(done, total)` | `done`, `total`, `seq` |
+| `job.result_chunk` | `ctx.result_chunk(chunk)` | `chunk`, `seq` |
+| `job.completed` | Agent returned | `result`, `seq` |
+| `job.failed` | Agent raised an exception | `error`, `seq` |
+| `job.cancelled` | Job cancelled | `seq` |
+| `job.heartbeat` | Runtime keep-alive | `seq` |
+
+## Subscribing to events
+
+### Await completion only
+
+```python
+handle = await client.submit(agent="echo", input={"x": 1})
+result = await handle.done
+```
+
+### Iterate all events
+
+```python
+handle = await client.submit(agent="echo", input={"x": 1})
+async for event in handle.events():
+    match event.kind:
+        case "job.log":
+            print(f"[{event.level}] {event.message}")
+        case "job.progress":
+            print(f"Progress: {event.done}/{event.total}")
+        case "job.result_chunk":
+            print(f"Chunk: {event.chunk}")
+        case "job.completed":
+            print(f"Result: {event.result}")
+            break
+        case "job.failed":
+            raise RuntimeError(event.error)
+```
+
+### Subscribe without a job handle
+
+Use `client.subscribe()` to attach to an existing job by ID:
+
+```python
+sub = await client.subscribe(job_id="job-abc123")
+async for event in sub.events():
+    ...
+```
+
+## Event acknowledgement
+
+By default, events are auto-acknowledged. For explicit backpressure control:
+
+```python
+handle = await client.submit(
+    agent="chunky",
+    input={},
+    auto_ack=False,
+)
+async for event in handle.events():
+    process(event)
+    await handle.ack(event.seq)  # acknowledge after processing
+```
+
+The runtime will not send the next event until the previous one is acknowledged.
+
+## Typed event objects
+
+Events are Pydantic models with a discriminated union on `kind`. You can use `isinstance` checks or `match` statements:
+
+```python
+from arcp import JobLogEvent, JobProgressEvent, JobCompletedEvent
+
+async for event in handle.events():
+    if isinstance(event, JobLogEvent):
+        logger.info(event.message)
+    elif isinstance(event, JobCompletedEvent):
+        return event.result
+```
+
+## Related
+
+- [Jobs guide](jobs.md)
+- [Stream resume guide](resume.md)
+- [Ack / backpressure recipe](../recipes/ack-backpressure.md)
+- [Subscribe recipe](../recipes/subscribe.md)