TINYDOC-3686: Correct the TinyMCE AI pages against the hosted API spec, the plugin, and AI service image 1.3.0.

modules/ROOT/pages/tinymceai-actions.adoc

@@ -119,7 +119,7 @@ Custom actions can be added to the list, and default actions can be removed or r
 The following table lists built-in Quick Actions. 
 
 * The **Editor** column is the label in the Quick Actions menu when that action is available in the editor.
-* The **Menu or control ID** column lists values for `tinymceai_quickactions_menu`, `tinymceai_quickactions_chat_prompts`, `tinymceai_quickactions_change_tone_menu`, and the toolbar when adding individual controls (see xref:tinymceai-actions.adoc#configuring-quick-actions-menu[Configuring Quick Actions menu]).
+* The **Menu or control ID** column lists values for `tinymceai_quickactions_menu`, `tinymceai_quickactions_chat_prompts`, `tinymceai_quickactions_change_tone_menu`, and the toolbar when adding individual controls (see xref:tinymceai-actions.adoc#configuring-quick-actions-menu[Configuring Quick Actions menu]). To put tones on the toolbar, add the `ai-quickactions-change-tone` menu button. It opens the tones set in xref:tinymceai.adoc#tinymceai_quickactions_change_tone_menu[`+tinymceai_quickactions_change_tone_menu+`]. The individual `ai-quickactions-tone-*` identifiers are menu items only, so they cannot be added to the toolbar.
 * The **System `actionName` or quick-action prompt id** column is the service identifier. Preview actions use a system `actionName` with the xref:tinymceai-actions.adoc#actions-api[Actions API]. Chat actions use a quick-action prompt id and xref:tinymceai-chat.adoc[Chat] with a pre-filled prompt, not the system actions API.
 
 [cols="1,3,2,3,1,1",options="header"]
@@ -261,7 +261,7 @@ Actions use streaming output with Server-Sent Events for real-time feedback as r
 
 Built-in Quick Actions—including identifiers, descriptions, and whether each command uses the system Actions API or Chat (Conversations API)—are summarized in xref:tinymceai-actions.adoc#quick-actions-reference-table[Default Actions].
 
-To run a system action, use https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/callSystemAction[Call a system action] with an `+actionName+` from the rows that have a checkmark in the **API** column of the table above. System actions use built-in prompts, so the request needs no prompt or model. For the token scopes that each system action needs, see xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions].
+To run a system action, use https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/callSystemAction[Call a system action] with an `+actionName+` from the rows that have a checkmark in the **API** column of the table above. System actions use built-in prompts, so the request needs no prompt or model. The `+translate+` action also takes the target language in `+args.language+`. For the token scopes that each system action needs, see xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions].
 
 For endpoint details, request and response schemas, authentication, and streaming behavior for system `actionName` calls, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions[Actions API].
 
@@ -272,7 +272,7 @@ In addition to system actions, custom actions can be created for specific use ca
 
 Unlike system actions that use default identifiers, custom actions use a unified endpoint, https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/callCustomAction[Call a custom action], where the transformation behavior is defined through a prompt parameter. See https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions[Actions API] for the custom actions endpoint and implementation details.
 
-Custom actions require the `ai:actions:custom` permission in the JWT token. See xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions].
+Custom actions require the `ai:actions:custom` permission and the permission for the requested model in the JWT token. See xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions] and xref:tinymceai-permissions.adoc#model-permissions[Model permissions].
 
 [[actions-streaming]]
 === Streaming Responses
@@ -284,6 +284,8 @@ Actions use Server-Sent Events (SSE) for real-time streaming results. See the xr
 
 The https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions[Actions API] reference (interactive OpenAPI documentation) is the full source for system and custom action endpoints, request and response schemas, authentication, worked examples, and streaming action responses.
 
+To record user feedback on a result, https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/addSystemActionRating[rate a system action call] or https://tinymceai.api.tiny.cloud/v1/docs#tag/Actions/operation/addCustomActionRating[rate a custom action call] with the `+callId+` from the `+action-metadata+` event of the action stream.
+
 [[related-features]]
 == Related Features
 

modules/ROOT/pages/tinymceai-api-overview.adoc

@@ -41,7 +41,7 @@ The following pages cover the AI service architecture and configuration.
 [[versioning]]
 == Versioning
 
-The version of each endpoint is part of its path, for example `+/v1/conversations+`. The {pluginname} plugin calls the `+/v1+` endpoints, and requests the model list with compatibility version `+1+`. The compatibility version is separate from the endpoint version. See xref:tinymceai-models.adoc#model-compatibility-versions[Model compatibility versions].
+The version of each endpoint is part of its path, for example `+/v1/conversations+`. The {pluginname} plugin calls the `+/v1+` endpoints, and requests the model list with compatibility version `+1+`. The compatibility version is separate from the endpoint version. Conversation messages also have version 1.1 endpoints under `+/v1.1+`, which can resume and cancel a reply stream. See xref:tinymceai-streaming.adoc#resumable-streams[Resumable reply streams]. See xref:tinymceai-models.adoc#model-compatibility-versions[Model compatibility versions].
 
 [[pagination]]
 == Pagination
@@ -102,7 +102,7 @@ The API reference lists every code in its https://tinymceai.api.tiny.cloud/v1/do
 [[rate-limit-errors]]
 === Rate limit errors
 
-For `+429+` responses with the code `+rate-limits-exceeded+`, see xref:tinymceai-limits.adoc#handling-rate-limit-errors[Handling rate limit errors].
+For `+429+` responses with the code `+rate-limits-exceeded+`, see xref:tinymceai-limits.adoc#handling-rate-limit-errors[Handling rate limit errors]. For `+403+` responses with the code `+usage-limits-exceeded+`, see xref:tinymceai-limits.adoc#usage-limits[Usage limits].
 
 [[resources-and-support]]
 == Resources and support

modules/ROOT/pages/tinymceai-chat.adoc

@@ -96,14 +96,14 @@ tinymce.init({
 
 Web search in Chat allows the AI to access and retrieve real-time information from the internet. Instead of relying only on pre-trained knowledge, the model can search the web to find up-to-date facts, verify details, and provide more accurate, current answers.
 
-Some models use web search automatically, while others may require manual activation. Whether the **Web search** toggle image:icons-premium/web-search.svg[Web search icon,24px] below the prompt input needs to be toggled depends on the model and sometimes even how the prompt is worded. For models that support web search, use the toggle button to enable it.
+To make web search available, turn on the **Web search** toggle image:icons-premium/web-search.svg[Web search icon,24px] below the prompt input. The toggle is available only when the selected model supports web search and the token includes the web search permission. See xref:tinymceai-permissions.adoc#conversation-permissions[Conversation permissions]. With the toggle on, the model decides from the prompt whether to search the web. A reply that used web search shows **Searched the internet for insights**. With the toggle off, the model does not search the web.
 
 [[reasoning]]
 === Reasoning
 
 Reasoning in Chat models turns on the ability to think through problems, draw logical conclusions, and make sense of complex information. It enables the model to analyze context, connect ideas, and produce well-structured, coherent answers beyond simple pattern matching.
 
-Some models use reasoning automatically, while others may require manual activation. Whether the **Reasoning** toggle image:icons-premium/reasoning.svg[Reasoning icon,24px] below the prompt input needs to be toggled depends on the model and sometimes even how the prompt is worded. For models that support reasoning, use the toggle button to enable it.
+The model reasons only when reasoning is enabled for the message, except for models that have xref:tinymceai-models.adoc#reasoning[reasoning always enabled]. For models that support reasoning, use the **Reasoning** toggle image:icons-premium/reasoning.svg[Reasoning icon,24px] below the prompt input to enable it.
 
 [[welcome-chat-actions]]
 == Customizing the welcome message
@@ -246,7 +246,9 @@ image::tinymceai/tinymce-ai-chat-diff-mode-reject-suggestion-overlay.png[{plugin
 [[chat-history]]
 == Chat history
 
-All past conversations appear in the Chat history. Click the image:icons/restore-draft.svg[Chat history icon,24px] button in the chat header to open the list. Click a conversation to reopen it, or use the menu on each entry to pin, rename, or delete it. Click **AI Chat** to return from the history view to the active conversation.
+Set xref:tinymceai.adoc#content_id[`+content_id+`] to a unique ID for each document, such as the ID of the document in the application. The plugin then stores each conversation with that ID, and the Chat history lists only the conversations for the open document, so a user who reopens the document finds its earlier conversations there. Without `+content_id+`, the Chat history lists all of the user's conversations, from every document.
+
+Click the image:icons/restore-draft.svg[Chat history icon,24px] button in the chat header to open the list. Click a conversation to reopen it, or use the menu on each entry to pin, rename, or delete it. Click **AI Chat** to return from the history view to the active conversation.
 
 The list shows pinned conversations under **Pinned**, and the other conversations under **History**.
 
@@ -259,7 +261,7 @@ Any conversation from the chat history can be continued as long as the AI model
 
 [NOTE]
 ====
-After a full page load or new browser session, reopening Chat does not automatically reconnect the editor to pending suggestions from an older conversation. Open that conversation again from Chat history so pending suggestions are linked to the current editor session before accepting or dismissing them.
+After a full page load or new browser session, reopening Chat does not automatically reconnect the editor to pending suggestions from an older conversation. Changes proposed in a conversation loaded from Chat history are shown as history and cannot be applied. Ask again in the current session to get new suggestions.
 ====
 
 [[conversations-api]]
@@ -289,11 +291,11 @@ The AI remembers everything that has been shared and builds on it throughout the
 [[conversations-api-flow]]
 === Sending a message through the API
 
-Sending a message through the API takes three requests. The token needs the conversation permissions for each request. See xref:tinymceai-permissions.adoc#conversation-permissions[Conversation permissions].
+To send a message through the API, follow these steps. The token needs the conversation permissions for each request. See xref:tinymceai-permissions.adoc#conversation-permissions[Conversation permissions].
 
 . https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/createConversation[Create the conversation].
-. Attach content: an https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Documents/operation/createDocument[HTML document], a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Files/operation/uploadFile[file], or a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[web page]. File size limits are listed in xref:tinymceai-limits.adoc#file-limits[File limits].
-. https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send the message]. The service streams the reply with Server-Sent Events (SSE). See xref:tinymceai-chat.adoc#conversations-streaming[Streaming responses].
+. Optional: attach content to the conversation, with one request for each item. Attach an https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Documents/operation/createDocument[HTML document], a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Files/operation/uploadFile[file], or a https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources/operation/downloadWebResources[web page]. Each request returns the `+id+` of the attached item. File size limits are listed in xref:tinymceai-limits.adoc#file-limits[File limits].
+. https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send the message], with each attached item in the `+content+` array as its type and `+id+`. See the example in xref:tinymceai-models.adoc#model-selection[Model Selection]. The service streams the reply with Server-Sent Events (SSE). See xref:tinymceai-chat.adoc#conversations-streaming[Streaming responses].
 
 [[conversations-api-capabilities]]
 === API capabilities
@@ -302,20 +304,26 @@ The `+capabilities+` object of a https://tinymceai.api.tiny.cloud/v1/docs#tag/Co
 
 Web search is separate from the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Web-Resources[Conversation Web Resources] endpoints, which attach the content of one known URL to the conversation.
 
+When a document in the conversation references images stored behind authentication, pass `+extraHttpHeaders+` in the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[message request] so the AI can fetch and describe those images. The headers are keyed by domain, and the service sends them only to the domains listed.
+
 [[conversations-api-stored]]
 === Working with stored conversations
 
-The Chat history in the sidebar shows the conversations and messages that the AI service stores. The following operations read and manage the same data:
+The AI service stores each conversation and its messages. The Chat history in the sidebar shows the same data. Back-end code can work with the stored conversations for tasks such as:
 
-* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversations[List conversations].
-* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversation[Get a conversation], https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/updateConversation[update a conversation] (for example, to rename or pin it), or https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/deleteConversation[delete a conversation].
-* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/getMessages[List the messages in a conversation].
+* *Finding the conversations for one document.* When xref:tinymceai.adoc#content_id[`+content_id+`] is set, the plugin creates each conversation in a group with that value. Pass the same value as `+group+` to https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations/operation/getConversations[list conversations] to get only the conversations for that document.
+* *Recording which suggestions users accept.* https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/addConversationMessageRating[Rate a reply] to record how many of its suggested changes the user accepted.
+* *Managing conversations across users.* A token with the `+ai:admin+` permission can read and delete the conversations of any user through the https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Admin[Conversation Admin] operations. Never return an `+ai:admin+` token to the editor. See xref:tinymceai-permissions.adoc#admin-permissions[Admin permissions].
+
+For every operation and its parameters, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversations[Conversations] and https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages[Conversation Messages] in the API reference.
 
 [[conversations-streaming]]
 === Streaming Responses
 
 Conversations use Server-Sent Events (SSE) for real-time streaming responses. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information and code examples. For the events and their payloads, see https://tinymceai.api.tiny.cloud/v1/docs#tag/Conversation-Messages/operation/createMessage[Send a message] in the API reference.
 
+With version 1.1 of the message endpoints, a client can resume an interrupted reply or cancel one in progress, when replay is available for that reply. See xref:tinymceai-streaming.adoc#resumable-streams[Resumable reply streams].
+
 [[conversations-api-reference]]
 === API Reference
 

modules/ROOT/pages/tinymceai-integration-options.adoc

@@ -5,7 +5,7 @@
 :description_short: Integration options for TinyMCE AI
 :keywords: AI, integration, plugin, API, AI service, tinymceai
 
-{pluginname} can be integrated with applications through two methods:
+{pluginname} can be integrated with applications through the following methods:
 
 [cols=2*a]
 |===
@@ -26,7 +26,7 @@ Use the AI service API to build custom integrations and workflows. Suitable for
 [.lead]
 xref:tinymceai-on-premises.adoc[**On-Premises Deployment**]
 
-Run the AI service as a self-hosted container within the host infrastructure, so document content, conversation history, and user data stay within the host network. Use it with the {pluginname} plugin or as a standalone service. Start with the xref:tinymceai-on-premises-getting-started.adoc[Getting started] guide.
+Run the AI service as a self-hosted container within the host infrastructure, so document content, conversation history, and user data are stored within the host network. Data sent to the configured LLM provider is processed by that provider. Use it with the {pluginname} plugin or as a standalone service. Start with the xref:tinymceai-on-premises-getting-started.adoc[Getting started] guide.
 
 a|
 |===