TINYDOC-3651: Correct and update the TinyMCE AI documentation for existing features.

modules/ROOT/pages/keyboard-shortcuts.adoc

@@ -53,9 +53,9 @@ This is a list of the keyboard shortcuts provided by premium plugins. Each short
 [cols=",,,",options="header"]
 |===
 |Action |Windows or Linux |macOS |Plugin
-|Open the AI Chat sidebar and move focus to it |Ctrl+J |⌘+J |xref:tinymceai.adoc[tinymceai]
-|Open the AI Review sidebar and move focus to it |Ctrl+Alt+S |Ctrl+Alt+S |xref:tinymceai.adoc[tinymceai]
-|Move focus to the AI Chat sidebar header or the AI preview toolbar |Ctrl+F9 |Ctrl+F9 |xref:tinymceai.adoc[tinymceai]
+|Open the AI Chat sidebar and move focus to the prompt input, or close it when focus is in the sidebar |Ctrl+J |⌘+J |xref:tinymceai.adoc[tinymceai]
+|Open the AI Review sidebar and move focus to it, or close it when focus is in the sidebar |Ctrl+Alt+S |Ctrl+Alt+S |xref:tinymceai.adoc[tinymceai]
+|Move focus to the AI Chat sidebar header, or from the AI preview toolbar to the toolbar of the selected suggestion |Ctrl+F9 |Ctrl+F9 |xref:tinymceai.adoc[tinymceai]
 |Open the AI dialog |Ctrl+J |⌘+J |xref:ai.adoc[ai]
 |Copy formatting |Ctrl+Alt+C |⌘+⌥+C |xref:formatpainter.adoc[formatpainter]
 |Apply formatting |Ctrl+Alt+V |⌘+⌥+V |xref:formatpainter.adoc[formatpainter]

modules/ROOT/pages/tinymceai-actions.adoc

@@ -31,7 +31,7 @@ Quick Actions fit transforming a selection or section (for example grammar fixes
 
 Both Quick Actions and Review can propose edits that apply only after acceptance or rejection. The main differences are scope and where the work happens in the editor:
 
-* *Quick Actions*: Operate on a selection or section (including the full document when the scope includes it). The Quick Actions menu runs one-off operations such as Chat with a pre-filled prompt, preview transformations, translation, and custom actions.
+* *Quick Actions*: Operate on a selection or section. When nothing is selected, a preview Quick Action (including a custom action of type `+action+`) runs on the whole document. When table cells are selected, the action runs on the selected cells. The Quick Actions menu runs one-off operations such as Chat with a pre-filled prompt, preview transformations, translation, and custom actions.
 * *Review*: Always analyzes the entire document in read-only Review mode. Suggestions appear in the Review sidebar and in the document. See xref:tinymceai-review.adoc[Review] for details.
 
 [[integration]]
@@ -124,23 +124,23 @@ The following table lists built-in Quick Actions.
 
 [cols="1,3,2,3,1,1",options="header"]
 |===
-|Editor |Menu or control ID |System `actionName`  |Description |Editor UI |API
+|Editor |Menu or control ID |System `actionName` or quick-action prompt id |Description |Editor UI |API
 
 |**Explain** |`ai-chat-explain` |`explain` |Opens Chat with the selected text and a pre-filled prompt. Uses the Conversations API, not the system actions path. |✓ |—
 
 |**Summarize** |`ai-chat-summarize` |`summarize` |Opens Chat with a summarize prompt. Uses the Conversations API, not the system actions path. |✓ |—
 
 |**Highlight key points** |`ai-chat-highlight-key-points` |`highlight-key-points` |Opens Chat with a key-points prompt. Uses the Conversations API, not the system actions path. |✓ |—
 
-|**Improve Writing** |`ai-quickactions-improve-writing` |`improve-writing` |Enhance clarity, word choice, and sentence structure. |✓ |✓
+|**Improve writing** |`ai-quickactions-improve-writing` |`improve-writing` |Enhance clarity, word choice, and sentence structure. |✓ |✓
 
-|**Continue Writing** |`ai-quickactions-continue-writing` |`continue` |Complete unfinished sentences, paragraphs, or entire documents. |✓ |✓
+|**Continue writing** |`ai-quickactions-continue-writing` |`continue` |Complete unfinished sentences, paragraphs, or entire documents. |✓ |✓
 
-|**Fix Grammar** |`ai-quickactions-check-grammar` |`fix-grammar` |Correct grammar, spelling, and punctuation errors. |✓ |✓
+|**Fix grammar & spelling** |`ai-quickactions-check-grammar` |`fix-grammar` |Correct grammar, spelling, and punctuation errors. |✓ |✓
 
 |**Change length** |`ai-quickactions-change-length` |`make-shorter`, `make-longer` |Shorten or lengthen the selection. Each option is its own system action. |✓ |✓
 
-|**Adjust Tone**
+|**Change tone**
 a|
 `ai-quickactions-change-tone` +
 `ai-quickactions-tone-casual` +
@@ -157,27 +157,16 @@ a|
 |Change writing style; each menu option maps to its own system action. |✓ |✓
 
 |**Translate**
-a|
-`ai-quickactions-translate` +
-`ai-quickactions-translate-english` +
-`ai-quickactions-translate-spanish` +
-`ai-quickactions-translate-russian` +
-`ai-quickactions-translate-swedish` +
-`ai-quickactions-translate-german` +
-`ai-quickactions-translate-japanese` +
-`ai-quickactions-translate-portuguese` +
-`ai-quickactions-translate-korean` +
-`ai-quickactions-translate-italian` +
-`ai-quickactions-translate-chinese`
-a|
-`translate`
-|Convert content between languages. Request body uses `args: { language: string }` with values such as `english`, `spanish`, `russian`, `swedish`, `german`, `japanese`, `portuguese`, `korean`, `italian`, or `chinese`. Configure the editor submenu with `tinymceai_languages`. |✓ |✓
+|`ai-quickactions-translate`
+|`translate`
+|Translate the selection into a language chosen from the **Translate** submenu. The submenu lists the languages set in xref:tinymceai.adoc#tinymceai_languages[`+tinymceai_languages+`]. Individual languages do not have menu item or toolbar button identifiers. |✓ |✓
 |===
 
 [NOTE]
 ====
 * A checkmark in the **Editor UI** column means the action can appear when included in `tinymceai_quickactions_menu` (and related sub-menu options such as `tinymceai_quickactions_chat_prompts`).
 * A checkmark in the **API** column means the action is invoked through the system Actions API path `+/v1/actions/system/{actionName}/calls+`. An em dash means the command is Chat-based and uses the Conversations API instead.
+* The `+ai-quickactions-custom+` identifier (labeled **Other**) lists the custom actions set in xref:tinymceai.adoc#tinymceai_quickactions_custom[`+tinymceai_quickactions_custom+`]. See xref:tinymceai-actions.adoc#custom-actions[Custom Actions].
 ====
 
 For system action endpoints, schemas, and streaming details, see the https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] reference.
@@ -272,21 +261,23 @@ 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/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].
+
 For endpoint details, request and response schemas, authentication, and streaming behavior for system `actionName` calls, see https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API].
 
 [[actions-custom-actions-api]]
 === Custom Actions through the API
 
 In addition to system actions, custom actions can be created for specific use cases through the API. Custom actions allow specialized content transformations using custom prompts to control AI behavior.
 
-Unlike system actions that use default identifiers, custom actions use a unified endpoint where the transformation behavior is defined through a prompt parameter. See https://tinymceai.api.tiny.cloud/docs#tag/Actions[Actions API] for the custom actions endpoint and implementation details.
+Unlike system actions that use default identifiers, custom actions use a unified endpoint, https://tinymceai.api.tiny.cloud/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/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.
+Custom actions require the `ai:actions:custom` permission in the JWT token. See xref:tinymceai-permissions.adoc#actions-permissions[Actions permissions].
 
 [[actions-streaming]]
 === Streaming Responses
 
-Actions use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information.
+Actions use Server-Sent Events (SSE) for real-time streaming results. See the xref:tinymceai-streaming.adoc[Streaming Responses guide] for detailed implementation information. For the events and their payloads, see https://tinymceai.api.tiny.cloud/docs#tag/Actions/operation/callSystemAction[Call a system action] and https://tinymceai.api.tiny.cloud/docs#tag/Actions/operation/callCustomAction[Call a custom action] in the API reference.
 
 [[actions-api-reference]]
 === API Reference

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

@@ -1,8 +1,10 @@
 = TinyMCE AI API Overview
 :navtitle: API overview
+:pluginname: TinyMCE AI
+:plugincode: tinymceai
 :description: Overview of TinyMCE AI service features and capabilities
 :description_short: API Overview
-:keywords: AI, API, AI service, overview, tinymceai
+:keywords: AI, API, AI service, overview, tinymceai, pagination, error codes, versioning
 
 The TinyMCE AI REST API enables AI integration within your application using the same infrastructure as the TinyMCE AI plugin, but without being tied to the editor. Integrate with multiple AI agents via one API, accessing all functionality from the Chat, Review, and Quick Actions features, with your own custom UI and workflows. 
 
@@ -12,12 +14,12 @@ The TinyMCE AI REST API enables AI integration within your application using the
 ====
 
 [[getting-started]]
-== Getting Started
+== Getting started
 
-New to TinyMCE AI? Start with the xref:tinymceai-api-quick-start.adoc[Quick Start] guide to set up the environment, generate access credentials, and make the first API call.
+New to {pluginname}? Start with the xref:tinymceai-api-quick-start.adoc[Quick Start] guide to set up the environment, generate access credentials, and make the first API call.
 
 [[tinymce-ai-features]]
-== TinyMCE AI features
+== {pluginname} features
 
 * xref:tinymceai-chat.adoc[**Chat**]: Interactive AI chats with history and persistent context.
 * xref:tinymceai-review.adoc[**Review**]: Content analysis and proofreading, optimized for larger content.
@@ -33,8 +35,74 @@ The following pages cover the AI service architecture and configuration.
 * xref:tinymceai-permissions.adoc[**Permissions**]: How to control user access to features.
 * xref:tinymceai-limits.adoc[**Limits**]: Rate limits, context size limits, and file restrictions.
 
+[[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].
+
+[[pagination]]
+== Pagination
+
+List endpoints use cursor pagination. These include the conversation list, and the documents, files, and web resources of a conversation. The API reference documents the pagination parameters on each list operation, for example https://tinymceai.api.tiny.cloud/docs#tag/Conversations/operation/getConversations[Fetch multiple conversations].
+
+[[error-responses]]
+== Error responses
+
+Errors returned by the AI service use a JSON body with these fields:
+
+[cols="1,3",options="header"]
+|===
+|Field |Description
+
+|`+statusCode+`
+|The HTTP status code.
+
+|`+code+`
+|A machine-readable error code, for example `+missing-permissions+`.
+
+|`+message+`
+|A short description of the error.
+
+|`+traceId+`
+|A unique identifier for the request. Include it when contacting {supportname}.
+
+|`+data+`
+|Optional. An object with details specific to the error.
+
+|`+explanation+`
+|Optional. More detail about why the error occurred.
+
+|`+action+`
+|Optional. A suggested next step.
+|===
+
+For example, a token without the permission a request needs returns:
+
+[source,json]
+----
+{
+  "statusCode": 403,
+  "code": "missing-permissions",
+  "message": "The user is missing permissions",
+  "traceId": "8f3c1c2e-5b7a-4d0e-9a61-2f4c8e0b7d13",
+  "data": {
+    "missingPermissions": ["ai:conversations:write"]
+  }
+}
+----
+
+[[error-codes]]
+=== Error codes
+
+The API reference lists every code in its https://tinymceai.api.tiny.cloud/docs#section/Overview/Error-codes[Error codes] section. For token errors, see xref:tinymceai-jwt-authentication-intro.adoc#troubleshooting[JWT troubleshooting]. For a `+missing-permissions+` response, see xref:tinymceai-permissions.adoc[Permissions].
+
+[[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].
+
 [[resources-and-support]]
-== Resources and Support
+== Resources and support
 
 * **API Documentation**: link:https://tinymceai.api.tiny.cloud/docs[Complete API reference for TinyMCE AI].
 * **Customer Support**: link:https://www.tiny.cloud/contact/[Contact us] to get help from the support team or speak with sales.

modules/ROOT/pages/tinymceai-api-quick-start.adoc

@@ -15,7 +15,7 @@ Sign up for the link:{accountsignup}[{productname} Premium Features 14-day free
 The {productname} Premium Features free trial allows for testing SaaS services. For on-premises solutions, link:{contactpage}[contact us].
 ====
 
-== Getting Started
+== Getting started
 
 Every request to the {pluginname} APIs must include a JWT signed with a keypair from the Customer Portal. Signing must run on the application server so private keys are never exposed to the browser. The editor supplies each token by calling xref:tinymceai.adoc#tinymceai_token_provider[+tinymceai_token_provider+], which is typically implemented as a `fetch` to a backend URL that returns a signed JWT for the signed-in user.
 
@@ -64,7 +64,7 @@ Once the keypair is created, use it to sign JWTs in the token endpoint. For step
 * xref:tinymceai-with-jwt-authentication-php.adoc[JWT authentication (PHP)]: Complete PHP implementation guide
 
 [[api-integration]]
-== API Integration
+== API integration
 
 All features are accessible through the API at `https://tinymceai.api.tiny.cloud` with xref:tinymceai-jwt-authentication-intro.adoc[JWT authentication].
 
@@ -80,7 +80,7 @@ For feature documentation and API access information, see:
 link:https://tinymceai.api.tiny.cloud/docs[Complete API Documentation]: Full API reference with interactive examples for all endpoints.
 
 [[next-steps]]
-== Next Steps
+== Next steps
 
 After setting up the JWT endpoint, continue with:
 
@@ -91,4 +91,4 @@ After setting up the JWT endpoint, continue with:
 * xref:tinymceai-chat.adoc#conversations-api[Chat API]: Start with interactive AI discussions.
 * xref:tinymceai-review.adoc#reviews-api[Review API]: Add content improvement features.
 * xref:tinymceai-actions.adoc#actions-api[Quick Actions API]: Implement content transformation.
-* xref:tinymceai-api-overview.adoc[API Overview]: Optional high-level map of Chat, Review, Quick Actions, and related resources.
+* xref:tinymceai-api-overview.adoc[API overview]: Optional high-level map of Chat, Review, Quick Actions, and related resources.