docs: expand and reorganize mdBook docs (transports, server features, releases, quickstart)

book/src/README.md

@@ -1,32 +1,28 @@
 # a2a-cpp C++20 Agent2Agent (A2A) SDK Documentation
 
-Welcome to the **a2a-cpp** documentation for the C++20 Agent2Agent (A2A) SDK.
+**a2a-cpp** is a C++20 SDK for building Agent2Agent (A2A) protocol clients and servers. The current documented release focuses on production-oriented protocol coverage: REST, JSON-RPC, and gRPC transports; Agent Card discovery; task lifecycle APIs; streaming; push notification configuration APIs; authentication metadata propagation; interceptors; CMake package exports; and vcpkg-oriented packaging.
 
-Use this guide to:
+## What is included
 
-- install and build the SDK,
-- build A2A clients and servers,
-- select a transport (REST, JSON-RPC, or gRPC), and
-- integrate streaming and authentication.
+- Client API: `SendMessage`, `GetTask`, `ListTasks`, `CancelTask`, streaming send/subscribe, and task push-notification config lifecycle calls.
+- Server API: executor-driven dispatch for REST, JSON-RPC, and gRPC transports.
+- Discovery: public and extended Agent Card fetch plus preferred-interface resolution.
+- Streaming: client observers, cancellable stream handles, and server stream sessions.
+- Authentication hooks: client credential providers and server request metadata extraction.
+- Operational extensions: client/server interceptors, required-extension validation, task stores, task history ordering, UUIDv7 task IDs, and optional PostgreSQL stores.
+- Build integration: CMake 3.25+, C++20, installable CMake package exports, generated protobuf headers, and vcpkg overlay/public-registry preparation.
 
-## Start here
+## Recommended reading path
 
-- New to the SDK? Begin with the [Quickstart: Build and Run a REST Client](getting-started/quickstart.md).
-- Building a client workflow? Continue to [Send Messages with A2AClient](client/sending-messages.md).
-- Implementing server-side execution? Read [Custom Executor Design and Implementation](server/custom-executor.md).
-- Choosing a transport? Compare [REST Transport](transports/rest.md), [JSON-RPC Transport](transports/json-rpc.md), and [gRPC Transport](transports/grpc.md).
-- Securing requests? Review [Authentication Overview](auth/overview.md).
+1. [Installation and Build](getting-started/installation.md) for toolchain requirements and CMake options.
+2. [Quickstart](getting-started/quickstart.md) for a copy/paste example flow.
+3. [Client Overview](client/overview.md) or [Server Overview](server/overview.md), depending on your integration role.
+4. [Transports](transports/rest.md), [Streaming](streaming/overview.md), and [Authentication](auth/overview.md) for runtime design decisions.
+5. [API Reference](api-reference.md) when you need generated public-header details.
 
-## SDK scope and capabilities
+## Version and support notes
 
-The SDK supports production-focused A2A capabilities including:
-
-- Agent card discovery and task lifecycle APIs,
-- REST, JSON-RPC, and gRPC transport integrations,
-- Streaming event consumption,
-- Client credential providers and server auth metadata propagation,
-- Build integration with CMake and vcpkg.
-
-## Examples
-
-Curated CMake consumer examples live in the repository [`examples/`](../../examples/) directory and cover FetchContent plus installed-package usage.
+- See [Releases and Versions](releases.md) for current release details and versioning guidance.
+- The SDK is C++20-only and exports CMake targets under the `a2a::` namespace.
+- Package documentation describes vcpkg workflows only.
+- Examples are deterministic and are intended to run without external services unless the example README says otherwise.

book/src/SUMMARY.md

@@ -12,12 +12,15 @@
   - [Custom Executor](server/custom-executor.md)
   - [REST Server](server/rest-server.md)
   - [JSON-RPC Server](server/json-rpc-server.md)
-- [Transports](transports/rest.md)
+  - [Push Notifications](server/push-notifications.md)
+  - [Interceptors](server/interceptors.md)
+- [Transports](transports/overview.md)
+  - [REST](transports/rest.md)
   - [JSON-RPC](transports/json-rpc.md)
   - [gRPC](transports/grpc.md)
 - [Streaming](streaming/overview.md)
 - [Authentication](auth/overview.md)
+- [Releases and Versions](releases.md)
 - [Build](build/cmake.md)
   - [vcpkg](build/vcpkg.md)
-  - [Conan](build/conan.md)
 - [API Reference](api-reference.md)

book/src/api-reference.md

@@ -1,26 +1,24 @@
 # API Reference
 
-The C++ API reference is generated from public headers under `include/a2a/**` using Doxygen and is published with this documentation site.
+The generated C++ API reference is built from public headers under `include/a2a/**`.
 
-## Open the generated reference
+## Generated reference
 
-- [C++ API Reference (generated)](api/cpp/index.html)
+When published with the documentation site, open:
 
-## Coverage
+- [C++ API Reference](api/cpp/index.html)
 
-The generated API includes the public interfaces for:
-
-- Core primitives (`a2a::core`)
-- Client APIs and transports (`a2a::client`)
-- Server APIs and transports (`a2a::server`)
-- Authentication-related client hooks (`a2a::client::auth`)
-
-## Local regeneration
-
-From the repository root:
+## Generate locally
 
 ```bash
 ./scripts/generate_api_reference.sh
 ```
 
-By default this writes generated pages to `book-build/api/cpp`.
+The script writes generated pages to `book-build/api/cpp`.
+
+## Public API areas
+
+- `a2a::core`: results, errors, protocol constants, JSON/protobuf helpers, Agent Card support, task state helpers, and versioning.
+- `a2a::client`: `A2AClient`, transports, discovery, auth hooks, call options, interceptors, and streaming observers.
+- `a2a::server`: executor, dispatcher, transports, interceptors, task stores, task lifecycle helpers, push notifications, and Agent Card serialization.
+- `a2a::http`: shared outbound HTTP client abstraction used by default REST/JSON-RPC/discovery/push paths when libcurl is enabled.

book/src/auth/overview.md

@@ -1,32 +1,31 @@
-# Authentication Overview for A2A Client and Server Flows
+# Authentication and Authorization Hooks
 
-Client-side authentication hooks are provided in `include/a2a/client/auth.h`.
+The SDK provides hooks for carrying credentials and auth metadata. Your application remains responsible for credential storage, verification, authorization decisions, and audit policy.
 
-For end-to-end request flow context, pair this guide with [Send Messages with A2AClient](../client/sending-messages.md), [Custom Executor Design and Implementation](../server/custom-executor.md), and transport docs for [REST](../transports/rest.md) or [JSON-RPC](../transports/json-rpc.md).
+## Client credential providers
 
-## Supported client auth patterns
+`include/a2a/client/auth.h` includes providers for:
 
-- **API key auth** via `ApiKeyCredentialProvider`
-- **Bearer token auth** via `BearerTokenCredentialProvider`
-- **Custom header auth** via `CustomHeaderCredentialProvider`
-- **OAuth2 extension point** via `OAuth2BearerCredentialProvider`
+- API key headers.
+- Bearer token headers.
+- Custom header credentials.
+- OAuth2 bearer token extension points.
 
-## Server-side metadata extraction
+Use these with transport call options or request construction paths that support metadata injection.
 
-Server request context metadata (`RequestContext::auth_metadata`) is populated from inbound auth headers in REST and JSON-RPC transports. Executor logic can use this metadata for authorization and auditing.
+## Server metadata
 
-## mTLS notes
+REST, JSON-RPC, and gRPC server paths populate `RequestContext` with transport metadata. Executor or interceptor code can read this metadata to make authorization decisions.
 
-mTLS is transport/runtime-termination dependent. If your deployment terminates TLS before the SDK boundary, propagate verified client identity metadata safely into request headers/context. If transport-native mTLS is enabled in your stack, ensure certificate validation, trust store rotation, and least-privilege identity mapping are documented and tested.
+## Policy guidance
 
-## Operational guidance
+- Never hardcode secrets in source, examples, or tests.
+- Validate credentials before trusting request metadata.
+- Normalize auth failures so callers receive consistent protocol errors.
+- Avoid logging raw credentials.
+- Prefer short-lived tokens and managed secret storage.
+- Document how TLS or mTLS identity is terminated and propagated into the SDK boundary.
 
-- Do not hardcode secrets in source or test fixtures.
-- Rotate keys/tokens and keep credential lifetimes bounded.
-- Treat all inbound metadata as untrusted until validated against policy.
-- Test auth success and failure paths end-to-end through transport integration tests.
+## Example
 
-## References
-
-- `tests/integration/rest_server_transport_integration_test.cpp`
-- `README.md`
+See `examples/apps/auth_policy_server/main.cpp` for an auth-policy shape.

book/src/client/cancel-task.md

@@ -1,27 +1,19 @@
 # Cancel Task
 
-`CancelTask` requests cancellation of in-flight work.
+`A2AClient::CancelTask` asks the server to cancel in-flight work.
 
-## When to use
+## When to use cancellation
 
-- User explicitly aborts an operation.
-- Upstream deadline expires and work should stop.
-- Supervising process needs to reclaim resources.
+- A user aborts an operation.
+- A deadline expires upstream.
+- Supervising logic needs to reclaim compute or queue capacity.
 
-## Happy path
+## Semantics
 
-1. Keep the task ID returned by `SendMessage`.
-2. Issue `CancelTask` for that task ID.
-3. Confirm task moves to a terminal canceled state via `GetTask` or stream events.
+Cancellation is best-effort. A task can complete before the cancellation request is processed, and servers can reject cancellation for completed, unknown, or policy-protected tasks.
 
-## Operational context
+## Recommended behavior
 
-- Cancellation is best-effort; completion may race with cancellation.
-- Make cancellation idempotent in higher-level workflows.
-- Document user-visible semantics (for example, whether partial outputs are retained).
-
-## Failure scenarios
-
-- Unknown task ID.
-- Task already completed.
-- Task cannot be canceled due to policy/executor constraints.
+- Make higher-level cancellation idempotent.
+- Return or display the latest task state after cancellation attempts.
+- Preserve enough audit data to explain whether the task was canceled, completed, or rejected.

book/src/client/discovery.md

@@ -1,25 +1,35 @@
-# Discovery
+# Discovery and Agent Cards
 
-Discovery resolves where and how to call an A2A agent.
+Discovery resolves server capabilities before constructing a client transport.
 
-## Happy path
+## Public and extended cards
 
-1. Use `DiscoveryClient` to fetch an `AgentCard`.
-2. Use `AgentCardResolver` to select an endpoint and transport.
-3. Use resolved endpoint metadata to construct your client transport.
+`DiscoveryClient` supports:
 
-## Operational context
+- `Fetch(base_url)` for the standard Agent Card.
+- `FetchExtendedAgentCard(base_url)` for the extended Agent Card endpoint.
 
-- Cache discovery results where practical, with clear refresh strategy.
-- Handle missing/partial card metadata defensively.
-- Prefer explicit fallback order when multiple transports are available.
+Fetched cards are cached for `kDefaultDiscoveryCacheTtl` (300 seconds) unless a different TTL is supplied.
 
-## Failure scenarios
+## Interface resolution
 
-- Discovery endpoint unavailable.
-- Invalid or incomplete `AgentCard`.
-- Unsupported transport in discovered card.
+`AgentCardResolver::SelectPreferredInterface(card, preferred)` selects a `ResolvedInterface` for one of:
 
-## Example
+- `PreferredTransport::kRest`
+- `PreferredTransport::kJsonRpc`
+- `PreferredTransport::kGrpc`
 
-See `examples/apps/simple_client/main.cpp` for a minimal discovery flow.
+The result includes the transport, URL, security requirements, and security schemes needed to configure a client.
+
+## Operational guidance
+
+- Validate and log the selected endpoint during startup.
+- Prefer an explicit fallback order when cards advertise multiple transports.
+- Treat discovery metadata as untrusted input until validated.
+- Refresh cached cards after deployment or capability changes.
+
+## Related files
+
+- `include/a2a/client/discovery.h`
+- `include/a2a/core/agent_card/agent_card_provider.h`
+- `include/a2a/server/agent_card/agent_card_serializer.h`

book/src/client/get-task.md

@@ -1,26 +1,25 @@
-# Get Task
+# Get Task and List Tasks
 
-`GetTask` retrieves task state and associated outputs after a send operation.
+`GetTask` retrieves a single task by ID. `ListTasks` returns a paginated list of tasks through the client abstraction and supported transports.
 
-## When to use
+## GetTask flow
 
-- Polling task progress/state after `SendMessage`.
-- Fetching final task payloads when streaming is not enabled.
+1. Store the task ID from `SendMessage` or a stream event.
+2. Build `lf::a2a::v1::GetTaskRequest`.
+3. Call `A2AClient::GetTask`.
+4. Interpret task status, artifacts, and history according to your application policy.
 
-## Happy path
+## ListTasks flow
 
-1. Persist the returned task ID from `SendMessage`.
-2. Call `GetTask` with that task ID.
-3. Interpret status and outputs.
+`a2a::client::ListTasksRequest` contains:
 
-## Operational context
+- `page_size`
+- `page_token`
 
-- Retry transient failures with bounded backoff.
-- Enforce request deadlines to avoid hanging calls.
-- Record task IDs in logs/telemetry for traceability.
+The response includes task values plus `next_page_token`.
 
-## Failure scenarios
+## Operational guidance
 
-- Unknown task ID.
-- Task exists but has not produced outputs yet.
-- Authorization mismatch for task visibility.
+- Use bounded polling with backoff when not using streaming.
+- Enforce authorization checks on server-side task visibility.
+- Avoid exposing full task history to clients that do not need it.

book/src/client/overview.md

@@ -1,30 +1,38 @@
 # Client Overview
 
-Use `a2a::client::A2AClient` to interact with A2A servers over multiple transports.
+Use `a2a::client::A2AClient` with a concrete `ClientTransport` to call A2A servers.
 
-## Typical client flow
+## Client capabilities
 
-1. Discover an `AgentCard` with `DiscoveryClient`.
-2. Resolve endpoint details with `AgentCardResolver`.
-3. Construct a transport (`HttpJsonTransport` for REST, or `JsonRpcTransport` for JSON-RPC).
-4. Create `A2AClient` with that transport.
-5. Invoke operations such as:
-   - `SendMessage`
-   - `GetTask`
-   - `CancelTask`
-   - `SendStreamingMessage`
-   - `SubscribeTask`
+- `SendMessage`
+- `GetTask`
+- `ListTasks`
+- `CancelTask`
+- `SendStreamingMessage`
+- `SubscribeTask`
+- `CreateTaskPushNotificationConfig`
+- `GetTaskPushNotificationConfig`
+- `ListTaskPushNotificationConfigs`
+- `DeleteTaskPushNotificationConfig`
+- Client interceptors via `ClientInterceptor`
+- Per-call settings through `CallOptions`
+
+## Typical flow
+
+1. Fetch an Agent Card with `DiscoveryClient`.
+2. Select an endpoint with `AgentCardResolver::SelectPreferredInterface`.
+3. Construct `HttpJsonTransport`, `JsonRpcTransport`, or `GrpcTransport`.
+4. Create `A2AClient` with the transport.
+5. Invoke task, streaming, or push-notification APIs.
+6. Call `Destroy()` during shutdown when you need transport cleanup.
+
+## Default outbound HTTP
+
+When libcurl is available and `A2A_ENABLE_LIBCURL=ON`, default constructors/factories can perform buffered outbound REST, JSON-RPC, and discovery calls. For tests, custom TLS policy, mTLS, retries, or embedded runtimes, inject your own requester/fetcher callbacks.
 
 ## Runnable examples
 
+- `examples/apps/hello_agent/main.cpp`
 - `examples/apps/simple_client/main.cpp`
-- `examples/apps/rest_server/main.cpp`
-- `examples/apps/json_rpc_server/main.cpp`
 - `examples/apps/streaming_client/main.cpp`
-
-## Related chapters
-
-- [Sending Messages](sending-messages.md)
-- [Discovery](discovery.md)
-- [Get Task](get-task.md)
-- [Cancel Task](cancel-task.md)
+- `examples/apps/push_notifications/main.cpp`