CC-37879: update AiFoundation docs for neuron-ai v3 adoption

docs/dg/dev/ai/ai-foundation/ai-foundation-conversation-history.md

@@ -1,7 +1,7 @@
 ---
 title: Conversation History
 description: Persist and manage multi-turn conversations with conversation history using database storage
-last_updated: Apr 22, 2026
+last_updated: Apr 29, 2026
 keywords: foundation, ai, conversation history, conversation, context, database, multi-turn, dialogue, audit, logging, tracking
 template: howto-guide-template
 related:
@@ -176,6 +176,7 @@ class ConversationManager
             $formattedMessages[] = [
                 'type' => $message->getType(), // 'user', 'assistant', 'tool_call', 'tool_result'
                 'content' => $message->getContent(),
+                'reasoning' => $message->getReasoning(), // null when provider does not return reasoning
             ];
         }
 
@@ -256,7 +257,7 @@ public function getConversationHistoryCollection(
 - `conversationHistories` (ConversationHistoryTransfer[]): Array of conversation histories matching the criteria
   - Each ConversationHistoryTransfer contains:
     - `conversationReference` (string): The conversation reference
-    - `messages` (PromptMessageTransfer[]): Array of all messages in the conversation with types (user, assistant, tool_call, tool_result), content, and attachments
+    - `messages` (PromptMessageTransfer[]): Array of all messages in the conversation with types (user, assistant, tool_call, tool_result), content, reasoning, and attachments
 
 ## Message types
 

docs/dg/dev/ai/ai-foundation/ai-foundation-module.md

@@ -1,7 +1,7 @@
 ---
 title: AiFoundation module Overview
 description: Integrate AI foundation providers into the Spryker application
-last_updated: Apr 22, 2026
+last_updated: May 5, 2026
 keywords: foundation, ai, neuron, prompt, aiconfiguration, openai, anthropic, bedrock, aws, ollama, gemini, deepseek, huggingface, mistral, grok, azure-openai, agent, chat history, conversation, audit, logging, tracking
 template: howto-guide-template
 label: early-access
@@ -443,6 +443,7 @@ This transfer represents a message in the conversation:
 - `content` (string): The text content of the message
 - `contentData` (array, optional): Additional structured data
 - `attachments` (Attachment[], optional): File or image attachments
+- `reasoning` (string, optional): Model chain-of-thought reasoning returned alongside the response. Only populated when the provider returns reasoning blocks (for example, Anthropic extended thinking). `null` when the provider does not return reasoning.
 
 ### PromptResponse
 
@@ -458,9 +459,16 @@ This transfer contains the AI response:
 This transfer represents a file or image attachment:
 
 - `type` (string): Type of attachment (use `AiFoundationConstants::ATTACHMENT_TYPE_IMAGE` or `ATTACHMENT_TYPE_DOCUMENT`)
-- `content` (string): The content (URL or Base64-encoded data)
-- `contentType` (string): Content type format (use `AiFoundationConstants::ATTACHMENT_CONTENT_TYPE_URL` or `ATTACHMENT_CONTENT_TYPE_BASE64`)
+- `content` (string): The content—URL, Base64-encoded data, or a provider-hosted file ID
+- `contentType` (string): Content type format: `ATTACHMENT_CONTENT_TYPE_URL`, `ATTACHMENT_CONTENT_TYPE_BASE64`, or `ATTACHMENT_CONTENT_TYPE_ID` (for provider-hosted file references such as OpenAI or Anthropic Files API IDs)
 - `mediaType` (string): MIME type (for example, `image/png`, `application/pdf`)
+- `filename` (string, optional): Original filename for document attachments. Only set when the type is `document` and the caller provides it.
+
+{% info_block warningBox "AWS Bedrock limitation" %}
+
+AWS Bedrock does not support URL-based attachments. When using AWS Bedrock as the provider, use `ATTACHMENT_CONTENT_TYPE_BASE64` to pass image or document content as Base64-encoded data instead of a URL.
+
+{% endinfo_block %}
 
 ### ToolInvocation
 
@@ -469,6 +477,8 @@ This transfer contains information about a tool invocation made by the AI:
 - `name` (string): The name of the tool that was invoked
 - `arguments` (array): The arguments passed to the tool
 - `result` (string): The result returned by the tool execution
+- `content` (string, optional): Assistant text emitted alongside the tool call (for example, "I will use the calculator now."). `null` when the model did not produce accompanying text.
+- `reasoning` (string, optional): Model chain-of-thought reasoning emitted alongside the tool call. `null` when the provider does not return reasoning blocks.
 
 ### StructuredMessage
 

docs/dg/dev/ai/ai-foundation/ai-foundation-tool-support.md

@@ -1,7 +1,7 @@
 ---
 title: Use AI tools with the AiFoundation module
 description: Extend AI capabilities by providing custom tools that AI models can invoke during conversations
-last_updated: Apr 22, 2026
+last_updated: Apr 29, 2026
 keywords: foundation, ai, tools, function calling, tool sets, plugins, openai, anthropic, prompt, agent, audit, logging
 template: howto-guide-template
 related:
@@ -450,6 +450,10 @@ if ($promptResponse->getIsSuccessful() === true) {
         $toolArguments = $toolInvocation->getArguments();
         $toolResult = $toolInvocation->getResult();
 
+        // content and reasoning are populated when the provider returns them alongside the tool call
+        $content = $toolInvocation->getContent();   // e.g. "I will search for that now."
+        $reasoning = $toolInvocation->getReasoning(); // chain-of-thought, when available
+
         // Log or process tool invocations
         $this->logger->info(sprintf(
             'AI invoked tool "%s" with arguments: %s. Result: %s',