Add API reference sections to documentation

Introduced detailed API reference sections to all major capability and core concept documentation pages, including chat, embeddings, images, speech, streaming, structured output, text, agents, pipelines, system prompts, and tools. These sections provide concise overviews of available methods, fluent APIs, response properties, and common usage patterns to improve developer experience and discoverability.

Author: timothymarois

docs/advanced/custom-providers.md

@@ -92,6 +92,47 @@ Atlas::agent('my-agent')
     ->chat('Hello');
 ```
 
+## API Reference
+
+```php
+// Agent provider configuration (override in agent class)
+public function provider(): ?string;                  // Provider name (e.g., 'openai', 'anthropic')
+public function model(): ?string;                     // Model name (e.g., 'gpt-4o', 'claude-sonnet-4-20250514')
+public function clientOptions(): array;               // HTTP client options
+public function providerOptions(): array;             // Provider-specific options
+
+// Runtime provider override
+Atlas::agent('agent')
+    ->withProvider(string $provider, ?string $model = null)  // Override provider and optionally model
+    ->withModel(string $model)                               // Override model only
+    ->withProviderOptions(array $options)                    // Provider-specific options
+    ->chat(string $input);
+
+// Direct Prism usage with providers
+Atlas::text()->using(string $provider, string $model);
+Atlas::image()->using(string $provider, string $model);
+Atlas::audio()->using(string $provider, string $model);
+Atlas::embeddings()->using(string $provider, string $model);
+Atlas::moderation()->using(string $provider, string $model);
+
+// Provider-specific options (via withProviderMeta or withProviderOptions)
+// Anthropic:
+->withProviderOptions(['cacheType' => 'ephemeral'])           // Prompt caching
+
+// OpenAI:
+->withProviderOptions([
+    'presence_penalty' => 0.5,    // -2.0 to 2.0
+    'frequency_penalty' => 0.3,   // -2.0 to 2.0
+    'logit_bias' => [],           // Token biases
+    'user' => 'user-123',         // End-user identifier
+])
+
+// Provider resolution order:
+// 1. withProvider() override (highest priority)
+// 2. Agent's provider() method
+// 3. Exception if neither set
+```
+
 ## Next Steps
 
 - [Chat](/capabilities/chat) — Chat configuration

docs/advanced/error-handling.md

@@ -225,6 +225,66 @@ class ChatController extends Controller
 }
 ```
 
+## API Reference
+
+```php
+// Atlas exception hierarchy
+use Atlasphp\Atlas\Exceptions\AtlasException;
+use Atlasphp\Atlas\Agents\Exceptions\AgentException;
+use Atlasphp\Atlas\Agents\Exceptions\AgentNotFoundException;
+use Atlasphp\Atlas\Agents\Exceptions\InvalidAgentException;
+use Atlasphp\Atlas\Tools\Exceptions\ToolException;
+use Atlasphp\Atlas\Tools\Exceptions\ToolNotFoundException;
+
+// Base exception - catch all Atlas errors
+try {
+    $response = Atlas::agent('agent')->chat('Hello');
+} catch (AtlasException $e) {
+    // Any Atlas configuration error
+}
+
+// Agent exceptions
+try {
+    $response = Atlas::agent('unknown')->chat('Hello');
+} catch (AgentNotFoundException $e) {
+    $e->getMessage();  // "No agent found with key 'unknown'."
+} catch (InvalidAgentException $e) {
+    $e->getMessage();  // Invalid agent configuration
+} catch (AgentException $e) {
+    // Any agent-related error
+}
+
+// Tool exceptions
+try {
+    $tool = $registry->get('unknown_tool');
+} catch (ToolNotFoundException $e) {
+    $e->getMessage();  // "Tool not found: unknown_tool"
+} catch (ToolException $e) {
+    // Any tool-related error
+}
+
+// ToolResult for tool error handling (don't throw, return errors)
+use Atlasphp\Atlas\Tools\Support\ToolResult;
+
+ToolResult::text(string $text): ToolResult;   // Success with text
+ToolResult::json(array $data): ToolResult;    // Success with JSON
+ToolResult::error(string $message): ToolResult; // Error result
+
+$result->succeeded(): bool;  // Check if successful
+$result->failed(): bool;     // Check if failed
+
+// Prism exceptions (pass through Atlas)
+// See: https://prismphp.com/advanced/error-handling.html
+use Prism\Prism\Exceptions\PrismException;
+use Prism\Prism\Exceptions\PrismRateLimitException;
+use Prism\Prism\Exceptions\PrismContextLengthExceededException;
+
+// Retry configuration (via Prism passthrough)
+Atlas::agent('agent')
+    ->withClientRetry(int $times, int $sleepMs)  // Automatic retries
+    ->chat('Hello');
+```
+
 ## Next Steps
 
 - [Pipelines](/core-concepts/pipelines) — Add error handling middleware

docs/advanced/testing.md

@@ -511,6 +511,75 @@ public function test_handles_provider_errors(): void
 </groups>
 ```
 
+## API Reference
+
+```php
+// Enabling fake mode
+$fake = Atlas::fake();                              // Returns AtlasFake instance
+$fake = Atlas::fake([PrismResponse $response]);     // With default response
+
+// Configuring fake responses
+$fake->response(string $agentKey): PendingFakeRequest;
+$fake->response(string $agentKey, PrismResponse $response): AtlasFake;
+$fake->sequence(array $responses): AtlasFake;       // Default sequence for any agent
+$fake->preventStrayRequests(): AtlasFake;           // Fail on unconfigured agents
+$fake->allowStrayRequests(): AtlasFake;             // Allow unconfigured agents
+$fake->reset(): AtlasFake;                          // Clear recorded requests
+
+// PendingFakeRequest fluent API
+$fake->response('agent-key')
+    ->return(PrismResponse $response): AtlasFake;
+    ->returnSequence(array $responses): AtlasFake;
+    ->throw(Throwable $exception): AtlasFake;
+    ->whenEmpty(PrismResponse|Throwable $response): PendingFakeRequest;
+
+// Creating fake Prism responses
+use Prism\Prism\Text\Response as PrismResponse;
+use Prism\Prism\ValueObjects\Usage;
+use Prism\Prism\Enums\FinishReason;
+
+// Simple text response
+new PrismResponse(
+    text: 'Hello! How can I help?',
+    finishReason: FinishReason::Stop,
+    usage: new Usage(promptTokens: 10, completionTokens: 20),
+);
+
+// Assertion methods
+$fake->assertCalled(): void;                        // Any agent called
+$fake->assertCalled(string $agentKey): void;        // Specific agent called
+$fake->assertCalledTimes(string $agentKey, int $times): void;
+$fake->assertNotCalled(string $agentKey): void;
+$fake->assertNothingCalled(): void;
+$fake->assertSent(Closure $callback): void;         // Custom assertion
+$fake->assertSentWithContext(string $key, mixed $value = null): void;
+$fake->assertSentWithSchema(): void;
+$fake->assertSentWithInput(string $needle): void;
+
+// Accessing recorded requests
+$fake->recorded(): array;                           // All RecordedRequest objects
+$fake->recordedFor(string $agentKey): array;        // For specific agent
+
+// RecordedRequest properties and methods
+$request->agent;                                    // AgentContract instance
+$request->input;                                    // User input string
+$request->context;                                  // ExecutionContext
+$request->response;                                 // PrismResponse
+$request->timestamp;                                // Unix timestamp
+$request->agentKey(): string;
+$request->inputContains(string $needle): bool;
+$request->hasMetadata(string $key, mixed $value = null): bool;
+$request->hasPrismCall(string $method): bool;
+$request->getPrismCallArgs(string $method): ?array;
+
+// Cleanup
+Atlas::unfake();                                    // Restore real executor
+$fake->restore();                                   // Alternative restore method
+
+// Auto-cleanup trait
+use Atlasphp\Atlas\Testing\Concerns\InteractsWithAtlasFake;
+```
+
 ## Next Steps
 
 - [Agents](/core-concepts/agents) — Build testable agents

docs/capabilities/chat.md

@@ -276,6 +276,80 @@ if ($response->text !== null) {
 
 See [Prism Response](https://prismphp.com/core-concepts/text-generation.html#the-response-object) for the complete response API.
 
+## API Reference
+
+```php
+// Agent chat fluent API
+Atlas::agent(string|AgentContract $agent)
+    // Context configuration
+    ->withMessages(array $messages)                       // Conversation history
+    ->withVariables(array $variables)                     // System prompt variables
+    ->withMetadata(array $metadata)                       // Pipeline/tool metadata
+
+    // Provider overrides
+    ->withProvider(string $provider, ?string $model)      // Override provider/model
+    ->withModel(string $model)                            // Override model only
+
+    // Attachments
+    ->withMedia(Image|Document|Audio|Video|array $media)  // Attach media (builder style)
+
+    // Structured output
+    ->withSchema(SchemaBuilder|ObjectSchema $schema)      // Schema for structured response
+    ->usingAutoMode()                                     // Auto schema mode (default)
+    ->usingNativeMode()                                   // Native JSON schema mode
+    ->usingJsonMode()                                     // JSON mode (for optional fields)
+
+    // Prism passthrough methods
+    ->withToolChoice(ToolChoice $choice)                  // Tool selection (Auto, Any, None)
+    ->withMaxTokens(int $tokens)                          // Max response tokens
+    ->withTemperature(float $temp)                        // Sampling temperature
+    ->usingTopP(float $topP)                              // Top-p sampling
+    ->usingTopK(int $topK)                                // Top-k sampling
+    ->withClientRetry(int $times, int $sleepMs)           // Retry with backoff
+    ->withClientOptions(array $options)                   // HTTP client options
+    ->withProviderOptions(array $options)                 // Provider-specific options
+
+    // Execution
+    ->chat(string $input, array $attachments = []): PrismResponse|StructuredResponse;
+    ->stream(string $input, array $attachments = []): Generator<StreamEvent>;
+
+// Response properties (PrismResponse)
+$response->text;                    // Generated text
+$response->usage->promptTokens;     // Input tokens
+$response->usage->completionTokens; // Output tokens
+$response->steps;                   // Multi-step agentic loop history
+$response->toolCalls;               // Tool calls made
+$response->toolResults;             // Tool execution results
+$response->finishReason;            // FinishReason enum
+$response->meta;                    // Request metadata
+
+// Response properties (StructuredResponse - when using withSchema)
+$response->structured;              // Extracted structured data array
+$response->text;                    // Raw text (if available)
+$response->usage;                   // Token usage stats
+
+// Message formats for withMessages()
+// Array format (for persistence):
+[
+    ['role' => 'user', 'content' => 'Hello'],
+    ['role' => 'assistant', 'content' => 'Hi there!'],
+]
+
+// Prism message objects (for full API access):
+[
+    new UserMessage('Hello'),
+    new AssistantMessage('Hi there!'),
+]
+
+// Prism media objects for attachments
+Image::fromUrl(string $url): Image;
+Image::fromLocalPath(string $path): Image;
+Image::fromBase64(string $data, string $mimeType): Image;
+Image::fromStoragePath(string $path, string $mimeType, ?string $disk): Image;
+Image::fromFileId(string $fileId): Image;
+// Same methods available on Document, Audio, Video
+```
+
 ## Next Steps
 
 - [Streaming](/capabilities/streaming) — Real-time streaming responses

docs/capabilities/embeddings.md

@@ -39,7 +39,7 @@ foreach ($response->embeddings as $index => $vector) {
 }
 ```
 
-## Semantic Search Example
+## Example: Semantic Search
 
 ```php
 // Index documents
@@ -69,7 +69,7 @@ $results = Document::query()
     ->get();
 ```
 
-## RAG Implementation
+## Example: RAG Implementation
 
 Combine embeddings with agents for retrieval-augmented generation:
 
@@ -197,6 +197,38 @@ class LogEmbeddings implements PipelineContract
 $registry->register('embeddings.after_embeddings', LogEmbeddings::class);
 ```
 
+## API Reference
+
+```php
+// Embeddings fluent API
+Atlas::embeddings()
+    ->using(string $provider, string $model)              // Set provider and model
+    ->fromInput(string|array $input)                      // Text(s) to embed
+    ->withProviderMeta(string $provider, array $options)  // Provider-specific options
+    ->withMetadata(array $metadata)                       // Pipeline metadata
+    ->asEmbeddings(): EmbeddingsResponse;
+
+// Response properties (EmbeddingsResponse)
+$response->embeddings;           // array of embedding vectors
+$response->embeddings[0];        // First embedding (array of floats)
+$response->usage->tokens;        // Tokens used
+
+// Common models
+->using('openai', 'text-embedding-3-small')   // 1536 dimensions, cheaper
+->using('openai', 'text-embedding-3-large')   // 3072 dimensions, more accurate
+->using('openai', 'text-embedding-ada-002')   // 1536 dimensions, legacy
+
+// Single vs batch input
+->fromInput('Single text to embed')
+->fromInput(['Text one', 'Text two', 'Text three'])  // Batch (more efficient)
+
+// Provider options (via withProviderMeta)
+->withProviderMeta('openai', [
+    'dimensions' => 512,         // Reduce dimensions (text-embedding-3-* only)
+    'encoding_format' => 'float' // 'float' or 'base64'
+])
+```
+
 ## Next Steps
 
 - [Prism Embeddings](https://prismphp.com/core-concepts/embeddings.html) — Complete embeddings reference

docs/capabilities/images.md

@@ -46,7 +46,7 @@ Storage::put('images/lake.png', $imageContent);
 Http::sink(storage_path('images/lake.png'))->get($response->images[0]->url);
 ```
 
-## Complete Example
+## Example: Complete Image Generation
 
 ```php
 use Atlasphp\Atlas\Atlas;
@@ -110,6 +110,38 @@ class LogImageGeneration implements PipelineContract
 $registry->register('image.after_generate', LogImageGeneration::class);
 ```
 
+## API Reference
+
+```php
+// Image generation fluent API
+Atlas::image()
+    ->using(string $provider, string $model)              // Set provider and model
+    ->withPrompt(string $prompt)                          // Image description
+    ->withSize(int $width, int $height)                   // Image dimensions
+    ->withProviderMeta(string $provider, array $options)  // Provider-specific options
+    ->withMetadata(array $metadata)                       // Pipeline metadata
+    ->generate(): ImageResponse;
+
+// Response properties (ImageResponse)
+$response->images;              // array of Image objects
+$response->images[0]->url;      // URL to generated image
+$response->images[0]->base64;   // Base64 encoded image (if requested)
+$response->images[0]->revisedPrompt;  // Revised prompt (if modified by provider)
+
+// Common provider options (via withProviderMeta)
+// OpenAI DALL-E 3:
+->withProviderMeta('openai', [
+    'quality' => 'standard',     // 'standard' or 'hd'
+    'style' => 'vivid',          // 'vivid' or 'natural'
+    'response_format' => 'url',  // 'url' or 'b64_json'
+])
+
+// Common sizes
+->withSize(1024, 1024)   // Square (DALL-E 3)
+->withSize(1792, 1024)   // Landscape (DALL-E 3)
+->withSize(1024, 1792)   // Portrait (DALL-E 3)
+```
+
 ## Next Steps
 
 - [Prism Image Generation](https://prismphp.com/core-concepts/image-generation.html) — Complete image reference