diff --git a/docs/_static/images/espocrm-extensions/ai/features/admin-settings-ai-features-tab.png b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-ai-features-tab.png
new file mode 100644
index 000000000..6cc57f03b
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-ai-features-tab.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/admin-settings-general-tap.png b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-general-tap.png
new file mode 100644
index 000000000..7db1e317d
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-general-tap.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/admin-settings-response-cache-tab.png b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-response-cache-tab.png
new file mode 100644
index 000000000..9c4c6ea05
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-response-cache-tab.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/admin-settings-token-limits-tab.png b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-token-limits-tab.png
new file mode 100644
index 000000000..19106e879
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-token-limits-tab.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/admin-settings-translate-tab.png b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-translate-tab.png
new file mode 100644
index 000000000..0e1821ed0
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/admin-settings-translate-tab.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-admin-assistant-page.png b/docs/_static/images/espocrm-extensions/ai/features/ai-admin-assistant-page.png
new file mode 100644
index 000000000..c29a209b2
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-admin-assistant-page.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-chat-entity-manager.png b/docs/_static/images/espocrm-extensions/ai/features/ai-chat-entity-manager.png
new file mode 100644
index 000000000..1b6c4e35f
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-chat-entity-manager.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-chat-panel.png b/docs/_static/images/espocrm-extensions/ai/features/ai-chat-panel.png
new file mode 100644
index 000000000..4195f7371
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-chat-panel.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-chat-prompts.png b/docs/_static/images/espocrm-extensions/ai/features/ai-chat-prompts.png
new file mode 100644
index 000000000..f6765f4c4
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-chat-prompts.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-create-list-button.png b/docs/_static/images/espocrm-extensions/ai/features/ai-create-list-button.png
new file mode 100644
index 000000000..51d8e4919
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-create-list-button.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-create-modal.png b/docs/_static/images/espocrm-extensions/ai/features/ai-create-modal.png
new file mode 100644
index 000000000..dc7889f76
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-create-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-log-detail.png b/docs/_static/images/espocrm-extensions/ai/features/ai-log-detail.png
new file mode 100644
index 000000000..3fbbe20dc
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-log-detail.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-log-list.png b/docs/_static/images/espocrm-extensions/ai/features/ai-log-list.png
new file mode 100644
index 000000000..ce1f8028c
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-log-list.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-prompt-variables.png b/docs/_static/images/espocrm-extensions/ai/features/ai-prompt-variables.png
new file mode 100644
index 000000000..37c015c6c
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-prompt-variables.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-role-scopes.png b/docs/_static/images/espocrm-extensions/ai/features/ai-role-scopes.png
new file mode 100644
index 000000000..48a6e0845
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-role-scopes.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/img_9.png b/docs/_static/images/espocrm-extensions/ai/features/ai-sandbox-page.png
similarity index 100%
rename from docs/_static/images/espocrm-extensions/ai/features/img_9.png
rename to docs/_static/images/espocrm-extensions/ai/features/ai-sandbox-page.png
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-summary-entity-manager.png b/docs/_static/images/espocrm-extensions/ai/features/ai-summary-entity-manager.png
new file mode 100644
index 000000000..24e3499b1
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-summary-entity-manager.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-summary-outdated-indicator.png b/docs/_static/images/espocrm-extensions/ai/features/ai-summary-outdated-indicator.png
new file mode 100644
index 000000000..9a4dd9038
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-summary-outdated-indicator.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/ai-summary-panel.png b/docs/_static/images/espocrm-extensions/ai/features/ai-summary-panel.png
new file mode 100644
index 000000000..ca03e8dd7
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/ai-summary-panel.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-analysis-panel.png b/docs/_static/images/espocrm-extensions/ai/features/email-analysis-panel.png
new file mode 100644
index 000000000..a58e10213
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-analysis-panel.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-composer-toolbar.png b/docs/_static/images/espocrm-extensions/ai/features/email-composer-toolbar.png
new file mode 100644
index 000000000..56b474013
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-composer-toolbar.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-detail-dropdown.png b/docs/_static/images/espocrm-extensions/ai/features/email-detail-dropdown.png
new file mode 100644
index 000000000..6a4bfe2b2
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-detail-dropdown.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-draft-modal.png b/docs/_static/images/espocrm-extensions/ai/features/email-draft-modal.png
new file mode 100644
index 000000000..803bebde9
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-draft-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-template-body-toolbar.png b/docs/_static/images/espocrm-extensions/ai/features/email-template-body-toolbar.png
new file mode 100644
index 000000000..7b0c3a049
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-template-body-toolbar.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-template-form-button.png b/docs/_static/images/espocrm-extensions/ai/features/email-template-form-button.png
new file mode 100644
index 000000000..afaa3b09e
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-template-form-button.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-template-form-modal.png b/docs/_static/images/espocrm-extensions/ai/features/email-template-form-modal.png
new file mode 100644
index 000000000..86aaf1af2
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-template-form-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-template-modal.png b/docs/_static/images/espocrm-extensions/ai/features/email-template-modal.png
new file mode 100644
index 000000000..5c7d43d31
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-template-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-thread-analysis-modal.png b/docs/_static/images/espocrm-extensions/ai/features/email-thread-analysis-modal.png
new file mode 100644
index 000000000..70b0282ab
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-thread-analysis-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-translate-button.png b/docs/_static/images/espocrm-extensions/ai/features/email-translate-button.png
new file mode 100644
index 000000000..2f5535960
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-translate-button.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/email-translate-modal.png b/docs/_static/images/espocrm-extensions/ai/features/email-translate-modal.png
new file mode 100644
index 000000000..0e13913a8
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/email-translate-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/field-ai-setup.png b/docs/_static/images/espocrm-extensions/ai/features/field-ai-setup.png
new file mode 100644
index 000000000..f84ee30df
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/field-ai-setup.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/field-ai-text-custom-prompt.png b/docs/_static/images/espocrm-extensions/ai/features/field-ai-text-custom-prompt.png
new file mode 100644
index 000000000..8b69ee478
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/field-ai-text-custom-prompt.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/field-ai-text-menu.png b/docs/_static/images/espocrm-extensions/ai/features/field-ai-text-menu.png
new file mode 100644
index 000000000..1087698cf
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/field-ai-text-menu.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/field-ai-wysiwyg-toolbar.png b/docs/_static/images/espocrm-extensions/ai/features/field-ai-wysiwyg-toolbar.png
new file mode 100644
index 000000000..15087ed6d
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/field-ai-wysiwyg-toolbar.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/image-analysis-field-button.png b/docs/_static/images/espocrm-extensions/ai/features/image-analysis-field-button.png
new file mode 100644
index 000000000..411f3bb16
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/image-analysis-field-button.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/image-analysis-modal.png b/docs/_static/images/espocrm-extensions/ai/features/image-analysis-modal.png
new file mode 100644
index 000000000..e034105c1
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/image-analysis-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/image-generation-field-button.png b/docs/_static/images/espocrm-extensions/ai/features/image-generation-field-button.png
new file mode 100644
index 000000000..cdd02b2cd
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/image-generation-field-button.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/image-generation-modal.png b/docs/_static/images/espocrm-extensions/ai/features/image-generation-modal.png
new file mode 100644
index 000000000..4b635f116
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/image-generation-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/image-preview-analyze-button.png b/docs/_static/images/espocrm-extensions/ai/features/image-preview-analyze-button.png
new file mode 100644
index 000000000..e034105c1
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/image-preview-analyze-button.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/img_10.png b/docs/_static/images/espocrm-extensions/ai/features/img_10.png
deleted file mode 100644
index 16012a8c7..000000000
Binary files a/docs/_static/images/espocrm-extensions/ai/features/img_10.png and /dev/null differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/pdf-template-modal.png b/docs/_static/images/espocrm-extensions/ai/features/pdf-template-modal.png
new file mode 100644
index 000000000..c0ba08e73
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/pdf-template-modal.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/smart-paste-list-button.png b/docs/_static/images/espocrm-extensions/ai/features/smart-paste-list-button.png
new file mode 100644
index 000000000..60be4b3cf
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/smart-paste-list-button.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/smart-paste-new-form.png b/docs/_static/images/espocrm-extensions/ai/features/smart-paste-new-form.png
new file mode 100644
index 000000000..9496a4490
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/smart-paste-new-form.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/stream-comment-ai-menu.png b/docs/_static/images/espocrm-extensions/ai/features/stream-comment-ai-menu.png
new file mode 100644
index 000000000..d04f11a57
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/stream-comment-ai-menu.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/token-usage-dashlets.png b/docs/_static/images/espocrm-extensions/ai/features/token-usage-dashlets.png
new file mode 100644
index 000000000..672dc462f
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/token-usage-dashlets.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/features/token-usage-list.png b/docs/_static/images/espocrm-extensions/ai/features/token-usage-list.png
new file mode 100644
index 000000000..afdf7c857
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/features/token-usage-list.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/setup/create-profile.png b/docs/_static/images/espocrm-extensions/ai/setup/create-profile.png
new file mode 100644
index 000000000..926e2a83b
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/setup/create-profile.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/setup/create-prompt.png b/docs/_static/images/espocrm-extensions/ai/setup/create-prompt.png
new file mode 100644
index 000000000..c3d88b89c
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/setup/create-prompt.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/setup/per-feature-profiles.png b/docs/_static/images/espocrm-extensions/ai/setup/per-feature-profiles.png
new file mode 100644
index 000000000..39de18a73
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/setup/per-feature-profiles.png differ
diff --git a/docs/_static/images/espocrm-extensions/ai/setup/select-default-profile.png b/docs/_static/images/espocrm-extensions/ai/setup/select-default-profile.png
new file mode 100644
index 000000000..d0aebf061
Binary files /dev/null and b/docs/_static/images/espocrm-extensions/ai/setup/select-default-profile.png differ
diff --git a/docs/espocrm-extensions/espocrm-ai/features/access-control.md b/docs/espocrm-extensions/espocrm-ai/features/access-control.md
index 2aa5dd9e5..2e0606a26 100644
--- a/docs/espocrm-extensions/espocrm-ai/features/access-control.md
+++ b/docs/espocrm-extensions/espocrm-ai/features/access-control.md
@@ -1,11 +1,83 @@
-!!! Info
-
- By default, regular and portal users don’t have access to AI features. Administrator needs to enable access in Roles.
+# Access Control
+Ebla AI uses EspoCRM's built-in **Roles** system together with normal entity permissions. In practice, users need:
+- The relevant **AI scope** enabled in their Role
+- The normal **read / create / edit** permission for the affected entity
-
+By default, regular and portal users do not have access to AI features until an Administrator enables them.
-!!! Note
+!!! info
- AI Sandbox feature is only available for Admin users
+ Navigate to **Administration → Roles** and enable the required AI scopes for the relevant Role.
+
+
+
+## Available AI Permission Scopes
+
+Each AI feature has its own permission scope:
+
+| Scope | Controls |
+|-------|----------|
+| `Ai` | Base AI access. Required for all AI-powered features. |
+| `AiChat` | Record-level AI Chat panel and Admin Assistant chat access |
+| `AiEmailComposer` | AI actions in email compose, reply, and email template body editing |
+| `AiFieldAction` | AI actions on text, varchar, wysiwyg, and stream comment content |
+| `AiFormula` | AI formula functions such as `eblaAi\textGenerate`, `eblaAi\runPrompt`, `eblaAi\analyzeImage`, `eblaAi\generateImage`, and `eblaAi\generateSpeech` |
+| `AiRecordSummary` | AI Summary panel on record detail views |
+| `AiSmartPaste` | Smart Paste on list views, relationship panels, and new-record forms |
+| `AiVision` | Image analysis and AI image generation |
+
+## How Feature Access Is Evaluated
+
+The AI scope alone is not enough. The user also needs the standard entity permission required by the feature.
+
+Examples:
+
+- **AI Chat** requires `Ai` + `AiChat` and read access to the current record
+- **AI Summary** requires `AiRecordSummary` and read access to the current record
+- **Smart Paste** requires `Ai` + `AiSmartPaste` and create or edit access to the target entity
+- **AI Create** requires `Ai` and create access to the target entity
+- **Email Translation** requires `Ai` and read access to Email
+- **Image Analysis / Generation** requires `Ai` + `AiVision`
+
+!!! note "Administrators"
+
+ Administrators can access the admin-facing Ebla AI pages, but normal record permissions still matter when a feature reads or writes CRM data.
+
+## Roles Configuration Tips
+
+Recommended patterns:
+
+- Grant `Ai` as the base permission first
+- Add only the feature scopes the role should use
+- Keep `AiChat`, `AiRecordSummary`, and `AiSmartPaste` separate so usage can be controlled more precisely
+- Grant `AiVision` only to users who should analyze or generate images
+
+## Token Usage Limits
+
+In addition to scope-based access control, Ebla AI supports token usage limits.
+
+### Per-User Override
+
+1. Navigate to **Administration → Users**.
+2. Open the user record.
+3. Set **AI Monthly Token Limit**.
+
+Even though the field name says **Monthly**, it acts as the user's personal token-limit override for the currently configured system period:
+
+- **Daily**
+- **Weekly**
+- **Monthly**
+
+Set it to `0` to fall back to the global default limit.
+
+### What Happens at the Limit
+
+When the effective limit is reached:
+
+- New AI requests are blocked
+- The user receives an error explaining that their token limit has been reached
+- Administrators are not blocked by token limits
+
+See [Token Usage Statistics](token-usage.md) for details.
diff --git a/docs/espocrm-extensions/espocrm-ai/features/admin-assistant.md b/docs/espocrm-extensions/espocrm-ai/features/admin-assistant.md
new file mode 100644
index 000000000..36fcb06e3
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/admin-assistant.md
@@ -0,0 +1,94 @@
+# AI Admin Assistant
+
+The AI Admin Assistant provides a full-page conversational workspace for EspoCRM administrators. It is designed for administrative and configuration tasks such as reviewing metadata, planning changes, helping with formulas, and assisting with entity or layout updates.
+
+Unlike the record-level **AI Chat** panel, this feature runs in **admin mode** and uses a broader tool set intended for CRM administration.
+
+!!! note
+
+ Experimental Feature — The AI Admin Assistant may use significant tokens and can produce incorrect answers. Always verify critical changes before applying them. Use it in a Sandbox environment only.
+
+
+
+## Where to Find It
+
+1. Navigate to **Administration**.
+2. Open the **Ebla AI Administration** section.
+3. Click **AI Assistant**.
+
+## Requirements
+
+- The user must be an **Administrator**.
+- The user must have access to AI chat features.
+- A default AI provider must be configured in **Administration → AI Settings**.
+- You can optionally assign a dedicated profile using **AI Admin Assistant Default Profile** in **Administration → AI Settings → AI Features**.
+
+## What It Can Help With
+
+Typical use cases include:
+
+- Explaining how a CRM area works
+- Creating new entity & relationship
+- Reviewing entity fields and layouts
+- Suggesting formula logic
+- Drafting translation labels
+- Helping plan changes before implementation
+- Assisting with admin-oriented CRM questions
+
+!!! note
+
+ The Admin Assistant is intended for administrators. It uses a broader tool set than record chat and should be treated as an administrative helper, not an unattended automation engine.
+
+## Interface Overview
+
+The page includes:
+
+- A main conversation area
+- A message input with multi-line support
+- Suggested starter prompts
+- A sidebar with saved conversations
+- A **New Chat** action
+- Per-message **Copy** buttons
+
+## Conversation Persistence
+
+The Admin Assistant keeps conversation history in two places:
+
+- **Browser-side conversation list** for quick switching between recent chats
+- **Server-side persisted history** so the active chat can continue across refreshes
+
+Current behavior:
+
+- Up to 30 recent conversations are kept in the browser list
+- Older browser-side conversations are trimmed automatically
+- Conversations older than 7 days are removed from the local sidebar list
+- The active server-side conversation is stored per admin conversation ID
+
+## Using the Assistant
+
+1. Open **Administration → AI Assistant**.
+2. Type your request in the message box.
+3. Press **Enter** to send, or use **Shift+Enter** for a new line.
+4. Review the response.
+5. Start a new conversation when you want a separate context.
+
+Examples:
+
+- "Explain how EspoCRM layouts work."
+- "Help me design fields for a custom Project entity."
+- "Draft a before-save formula that builds a reference number."
+- "What should I check before adding a many-to-many relationship?"
+
+## Best Practices
+
+- Be specific about the entity, field, or layout you are asking about.
+- Use separate chats for unrelated admin topics.
+- Review any suggested configuration carefully before applying it.
+- Use the AI Sandbox if you want to test prompts against a record context first.
+
+## Related Features
+
+- [AI Sandbox](sandbox.md) - Test prompts and record-aware instructions
+- [AI Profiles](ai-profiles.md) - Assign a dedicated profile to the assistant
+- [AI Chat Panel](ai-chat.md) - Record-level AI assistant for end users
+- [Admin Settings](admin-settings.md) - Configure the default profile used by the assistant
diff --git a/docs/espocrm-extensions/espocrm-ai/features/admin-settings.md b/docs/espocrm-extensions/espocrm-ai/features/admin-settings.md
new file mode 100644
index 000000000..7c538c0ce
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/admin-settings.md
@@ -0,0 +1,204 @@
+# Admin Settings
+
+Global AI settings are managed from **Administration → AI Settings**. These settings control provider selection, feature defaults, token limits, response caching, translation behavior, Smart Paste visibility, and Create with AI visibility.
+
+
+## General Tab
+
+The **General** tab contains the core extension-wide settings.
+
+
+
+### Default AI Provider
+
+The **Default AI Provider** setting determines which configured provider is used when a feature does not explicitly resolve another provider from an AI Profile.
+
+Most UI-based AI actions also expect a default provider to be set before their buttons become visible.
+
+### Default AI Profile
+
+The **Default AI Profile** is the fallback profile used when a feature does not have:
+
+- An entity-specific profile
+- A feature-specific default profile
+- A prompt-linked profile
+
+### Global AI Instructions
+
+The **Global AI Instructions** field lets you define text that is prepended to every AI request across the extension.
+
+Use this for:
+
+- Company-wide response rules
+- Tone and formatting guidance
+- Language instructions
+- Restrictions or compliance reminders
+
+!!! note
+
+ Global AI Instructions are combined with the selected AI Profile context and the feature-specific prompt. The global instructions are applied first.
+
+### Variable Substitution
+
+Global AI Instructions and AI Profile context fields support `{varName}` placeholders.
+
+**Always available:**
+
+| Variable | Replaced with |
+|----------|---------------|
+| `{userName}` | Current user's full name |
+| `{userRole}` | `Administrator` or `User` |
+| `{companyName}` | Company name from Settings |
+| `{today}` | Current date in `YYYY-MM-DD` format |
+| `{language}` | Current user's language code |
+
+**Available when a feature runs against a record context:**
+
+| Variable | Replaced with |
+|----------|---------------|
+| `{entityType}` | Entity type, such as `Contact` or `Opportunity` |
+| `{entityName}` | The record name |
+| `{entityId}` | The record ID |
+
+Unknown placeholders are left unchanged.
+
+## Translate Tab
+
+The **Translate** tab contains language and email-translation settings.
+
+
+### AI Translate Languages
+
+It controls the language list shown by translation actions in text fields, varchar fields, WYSIWYG fields, and stream comments.
+
+Behavior:
+
+- If one language is configured, the UI shows a single **Translate** action
+- If multiple languages are configured, the UI shows a **Translate To** sub-menu
+
+### Enable Email Translate
+
+Enable **Email Translate** to show the **Translate** button on Email detail views.
+
+### AI Email Translate Default Profile
+
+Set a dedicated profile if you want email translations to use a different model or context than the global default.
+
+### AI Email Translate Default Prompt
+
+Set the prompt used for the email translation request.
+
+!!! important
+
+ Email translation expects a translation prompt to be configured. For reliable use, set **AI Email Translate Default Prompt** explicitly.
+
+## Token Limits Tab
+
+
+
+### Default Token Limit
+
+The **Default Token Limit** sets the fallback system-wide token quota for non-admin users.
+
+- `0` means unlimited
+- Applies only when the user does not have a personal override
+
+### Token Limit Period
+
+The **Token Limit Period** defines the enforcement window:
+
+- **Daily**
+- **Weekly**
+- **Monthly**
+
+### Per-User Override
+
+Each user record has an **AI Monthly Token Limit** field. Even though the label says *Monthly*, the value acts as that user's personal override for the currently configured period.
+
+### Max Tool-Call Iterations
+
+It limits how many consecutive tool-call rounds the AI Chat engine can perform in one request.
+
+Use cases:
+
+- Lower values reduce cost and keep tool usage tight
+- Higher values help with more complex multi-step chat tasks
+
+## Response Cache Tab
+
+The response cache reuses identical AI responses for selected features.
+
+
+### Settings
+
+- **Response Cache**
+- **Cache TTL** in days
+
+### What Is Cached
+
+The current implementation uses response caching for several feature APIs, including:
+
+- Email composer actions
+- Email template generation
+- PDF template generation
+- Field text actions
+
+Some AI interactions are intentionally excluded, especially tool-using chat flows.
+
+### Cache Notes
+
+- Cached responses return faster
+- Cached responses do not consume new tokens on the cache-hit request
+- Cache hits are visible in **AI Log**
+
+## AI Features Tab
+
+This tab lets you assign default profiles per feature.
+
+| Setting | Used By |
+|---------|---------|
+| **Default AI Profile** | Global fallback for all features |
+| **AI Chat Default Profile** | Record-level AI Chat |
+| **AI Summary Default Profile** | AI Summary |
+| **AI Email Composer Default Profile** | Draft, reply, polish, grammar, tone |
+| **AI Field Action Default Profile** | Text field and stream comment AI actions |
+| **AI Smart Paste Default Profile** | Smart Paste |
+| **AI Vision Default Profile** | Image analysis and image generation |
+| **AI Admin Assistant Default Profile** | Admin Assistant |
+| **AI Email Translate Default Profile** | Email translation |
+
+
+## Smart Paste Scopes
+
+The **Smart Paste Scopes** field controls where Smart Paste buttons appear.
+
+Recommended configuration:
+
+1. Open **Administration → AI Settings → General**.
+2. Select the entity types you want to support.
+3. Save.
+
+!!! tip
+
+ Explicitly selecting the scopes gives the most predictable button visibility across main list views, relationship panels, and new-record forms.
+
+## AI Create Scopes
+
+The **AI Create Scopes** field controls where **Create with AI** appears.
+
+1. Open **Administration → AI Settings → General**.
+2. Select the entity types that should show **Create with AI**.
+3. Save.
+
+The button then appears:
+
+- In the main list view header
+- In supported relationship panel lists
+
+## Related Features
+
+- [AI Profiles](ai-profiles.md)
+- [AI Prompts](ai-prompts.md)
+- [AI Smart Paste](smart-paste.md)
+- [AI Create from List View](ai-create.md)
+- [Token Usage & Limits](token-usage.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/ai-chat.md b/docs/espocrm-extensions/espocrm-ai/features/ai-chat.md
new file mode 100644
index 000000000..9b17e2515
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/ai-chat.md
@@ -0,0 +1,120 @@
+# AI Chat Panel
+
+The AI Chat Panel adds a conversational assistant to supported record detail views. It lets users ask questions about the current record, related records, and CRM data without leaving the page.
+
+The chat can use AI tools, persist conversation history per user and record, and continue across refreshes.
+
+
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- `AiChat` access
+- Read access to the current record
+- A configured default AI provider
+
+## Enabling AI Chat for an Entity
+
+1. Navigate to **Administration → Entity Manager**.
+2. Open the entity you want to configure.
+3. Enable **AI Chat**.
+4. Optionally set **AI Chat Profile**.
+5. Save.
+
+
+
+## Using the AI Chat Panel
+
+1. Open a record detail view for an entity with AI Chat enabled.
+2. Find the **AI Chat** side panel.
+3. Type your message.
+4. Press **Enter** to send, or **Shift+Enter** for a new line.
+5. Review the response.
+
+## Current Record Context
+
+When the panel is used on a record, the AI automatically receives the current record context, including:
+
+- Entity type
+- Record ID
+- Record name
+
+This lets the user ask questions such as:
+
+- "What is the current stage of this opportunity?"
+- "How many open tasks are related to this account?"
+- "Summarize the recent activity on this contact."
+
+## Prompt Shortcuts
+
+If AI Prompts exist for the current entity or as global prompts, the chat panel shows a prompt shortcut button.
+
+The prompt menu combines:
+
+- Global prompts
+- Entity-specific prompts for the current record type
+
+Selecting one inserts and sends that prompt immediately.
+
+
+
+## Conversation Persistence
+
+Conversation history is stored per:
+
+- User
+- Entity type
+- Record
+
+This means:
+
+- Different users have separate chat history on the same record
+- Refreshing the page reloads the existing conversation
+- The **Clear** button deletes the stored conversation for that record and user
+
+## Long Conversation Compression
+
+When a conversation becomes long, older messages are automatically compressed into a summary so the chat can continue without carrying the entire raw history forever.
+
+Current behavior:
+
+- Compression starts after long multi-turn history
+- A summary of earlier messages is kept
+- The most recent raw messages remain available in full
+
+This reduces token usage while preserving the main context of the conversation.
+
+## Tool Access and AI Profile Tier
+
+The chat panel can use internal tools to answer CRM-aware questions.
+
+Tool availability depends on the **Formula Tier** of the resolved AI Profile:
+
+- **read** - Query CRM data
+- **write** - Read and write supported CRM data
+- **admin** - Administrative tools
+
+For normal record chat, `read` is the typical and safest choice.
+
+## Common Use Cases
+
+- Asking about the current record status
+- Reviewing related items
+- Counting related records
+- Exploring entity metadata
+- Asking for next-step guidance based on the visible CRM context
+
+## Notes
+
+- The AI uses the configured chat profile if one is assigned to the entity
+- If no entity-specific profile is set, the feature falls back to the **AI Chat Default Profile**, then the global default profile
+- Assistant messages can be copied directly from the panel
+
+## Related Features
+
+- [AI Summary Panel](ai-summary.md)
+- [AI Prompts](ai-prompts.md)
+- [AI Profiles](ai-profiles.md)
+- [AI Admin Assistant](admin-assistant.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/ai-create.md b/docs/espocrm-extensions/espocrm-ai/features/ai-create.md
new file mode 100644
index 000000000..4f456c4fa
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/ai-create.md
@@ -0,0 +1,72 @@
+# AI Create
+
+AI Create lets users describe a new CRM record in plain language and open the normal EspoCRM create form with suggested values already filled in.
+
+The feature is designed for fast first-pass record creation. Nothing is saved automatically until the user reviews the generated values in the standard form and clicks **Save**.
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- Create access to the target entity
+- A configured default AI provider
+
+Administrators also need to enable the entity in **Administration -> AI Settings -> General -> AI Create Scopes**.
+
+## Where the Button Appears
+
+When an entity is selected in **AI Create Scopes**, the **Create with AI** button appears:
+
+- In the main list view header
+- In supported relationship panel lists
+
+
+
+## Using AI Create
+
+1. Open the list view for a supported entity.
+2. Click **Create with AI**.
+3. Enter a plain-language description of the record you want to create.
+4. Click **Generate**.
+5. Review the AI suggestions shown in the preview area.
+6. Click **Open Form** to open the regular create form with the generated attributes.
+7. Review the values, make any changes you want, and save the record normally.
+
+
+
+## Description Rules
+
+- The description must contain at least `20` characters
+- A live counter is shown in the modal
+- The description is preserved when you click **Regenerate**
+
+Example:
+
+```text
+A new contact named Sarah Johnson, senior buyer at Acme Corp in New York, interested in our enterprise plan. Met at the trade show last week.
+```
+
+## What the Preview Shows
+
+The preview lists the field labels and the values extracted by the AI.
+
+If the AI cannot confidently map the description to specific fields, the modal still lets the user open the create form and complete the record manually.
+
+## Notes
+
+- The AI only fills fields that exist on the target entity
+- No record is created until the user opens the form and saves it
+- Better descriptions usually produce better field mapping
+- Relationship fields and advanced business logic may still need manual review in the final form
+
+## Tips
+
+- Mention names, companies, dates, priorities, and statuses explicitly
+- If an important field is missing, refine the description and click **Regenerate**
+
+## Related Features
+
+- [Smart Paste](smart-paste.md)
+- [AI Profiles](ai-profiles.md)
+- [Access Control](access-control.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/ai-profiles.md b/docs/espocrm-extensions/espocrm-ai/features/ai-profiles.md
index da52e93df..f717616dc 100644
--- a/docs/espocrm-extensions/espocrm-ai/features/ai-profiles.md
+++ b/docs/espocrm-extensions/espocrm-ai/features/ai-profiles.md
@@ -1,76 +1,163 @@
# AI Profiles (Contexts)
-AI Profiles is a feature of Ebla AI that allows users to create and manage AI profiles. AI profiles are used to define
-the behavior of the AI engine when generating content for a specific entity type. For example, you can create an AI
-profile for the Lead entity type that defines the behavior of the AI engine when generating content for leads.
+AI Profiles define how Ebla AI behaves for different use cases. A profile can specify the provider, model, tone, token settings, and AI tool access level used by a feature.
+
+Profiles are reusable and can be assigned:
+
+- As the global default profile
+- As a per-feature default profile
+- As an entity-specific AI Chat or AI Summary profile
+- Directly on an AI Prompt
+
+## Default Profile Templates
+
+On a fresh installation, Ebla AI seeds seven ready-to-use profiles:
+
+1. **General CRM Assistant**
+2. **Email Reply Assistant**
+3. **Sales Assistant**
+4. **Support Assistant**
+5. **Record Summarizer**
+6. **Content Writer**
+7. **Data Analyst**
+
+These provide practical starting points for common CRM use cases.
## Creating an AI Profile
-1. Navigate to **Administration** -> **AI Profiles**.
+1. Navigate to **Administration → AI Profiles**.
2. Click **Create**.
-3. Enter a name for the AI profile.
-4. Select the provider (Gemini - OpenAI - Ollama - Anthropic - OpenRouter). (Optional)
-5. Enter the context to be sent to the AI before the prompt is sent.
-
-### Parameters:
-
-- **Name**: The name of the AI profile.
-- **Provider**: The provider to use for the AI profile. (Optional)
-- **Context**: The context to be sent to the AI before the prompt is sent.
-- **Model**: The model which will generate the completion. Some models are suitable for natural language tasks, others
- specialize in code.
-- **Max Tokens**: The maximum number of tokens to generate shared between the prompt and completion. The exact limit
- varies by model. (One token is roughly 4 characters for standard English text).
-- **Temperature**: Controls randomness: Lowering results in less random completions.
- As the temperature approaches zero, the model will become deterministic and repetitive.
-- **Top K**: Controls diversity via nucleus sampling: 0.5 means half of all likelihood-weighted options are considered.
+3. Enter the profile details.
-!!! important
+
- If output is not as expected, you can click on **Send** button to regenerate the output.
+### Main Fields
-### Select default profile per Entity Type
+- **Name** - Profile name shown throughout the extension
+- **Provider** - Optional. Leave empty to use the current default AI provider
+- **Context** - System-style instructions for the AI
+- **Model** - Selected dynamically from the chosen provider
+- **Max Tokens** - Token budget used by the request
+- **Temperature** - Controls randomness
+- **Top K** - Additional sampling control
+- **Formula Tier** - Controls what AI Chat tools are available
-1. Navigate to **Administration** -> **Entity Manager** -> **Select Entity Type**.
-2. In the **AI Profile** field, select the AI profile you want to use for the entity type.
-3. Click **Save**.
+## Provider and Model Behavior
-!!! important
+### Provider
- The selected AI profile will be used by default for the entity type.
+If **Provider** is left empty, the profile inherits the configured **Default AI Provider** from AI Settings.
-## Examples
+### Model
-### Leads Score Calculation
-
-```
-Please use this person’s profile data to create lead scores.
+The **Model** field is populated dynamically based on the selected provider using the provider's available model list.
-{{targetData}}
+This means the model choices can differ across:
-The maximum value is 4. The minimum value is 0.
+- OpenAI
+- Gemini
+- Anthropic
+- OpenRouter
+- Ollama
-Please assign 1 point to profiles that have come from a campaign.
+## Context Field
-Please assign 1 point to profiles that from industry most likely go to trips.
+The **Context** field contains the reusable instructions sent with requests that use the profile.
-Please assign 1 point to profiles that lives on Europe.
+Typical examples:
-Please assign 1 point to profiles that have enterprise email.
+- "You are a concise CRM sales assistant."
+- "Always respond in professional British English."
+- "Focus on structured data extraction and return clean results."
-Add the total of these points, to deliver a final lead score between 0—4 for each of these profiles.
-```
+## Variable Substitution in Context
-
+The Context field supports `{varName}` placeholders. The same variables available in [Global AI Instructions](admin-settings.md#variable-substitution) can be used here.
-### Email Reply Assistant
+Example:
```
-You are a specialized assistant for crafting professional email responses. You expects users to paste an email they've received into the chat.
-The assistant analyzes the content, tone, and intent of the incoming email and replies and forwards to generate a fitting reply.
-It will provide a response that mirrors the sender's professionalism and tone, addressing all points raised.
-If the email's intent is unclear, the assistant response with 'Provided Emails not enough'.
-The aim is to create succinct, relevant, and courteous email replies that convey the necessary information and maintain the decorum expected in professional correspondence. The email subject is {{subject}} and the email body is {{bodyPlain}}.
+You are a CRM assistant for {companyName}.
+You are helping {userName} ({userRole}).
+Always respond in {language}.
```
-
\ No newline at end of file
+## Formula Tier
+
+The **Formula Tier** field is especially important for AI Chat and the Admin Assistant.
+
+Available values:
+
+- **read** - Read-only data tools
+- **write** - Read and write data tools
+- **admin** - Administrative tools such as entity, field, layout, translation, and formula helpers
+
+!!! important
+
+ Use `admin` only for carefully controlled administrative profiles. Record-level AI chat usually only needs `read`.
+
+## Default Usage Patterns
+
+Common profile strategies:
+
+- **General CRM Assistant** for chat and general AI features
+- **Record Summarizer** for AI Summary
+- **Email Reply Assistant** for compose and reply workflows
+- **Data Analyst** for Smart Paste or structured extraction
+
+## Assigning Profiles to Features
+
+Profiles can be assigned in several places.
+
+### Global or Per-Feature Defaults
+
+Navigate to **Administration → AI Settings → AI Features** and assign:
+
+- Chat profile
+- Summary profile
+- Email composer profile
+- Field action profile
+- Smart Paste profile
+- Vision profile
+- Admin Assistant profile
+- Email translation profile
+
+
+
+### Per Entity in Entity Manager
+
+For record-level features, you can assign profiles per entity:
+
+1. Navigate to **Administration → Entity Manager**.
+2. Open an entity.
+3. Configure:
+ - **AI Chat Profile**
+ - **AI Summary Profile**
+
+### On AI Prompts
+
+An AI Prompt can optionally link to a profile. This is useful when a specific prompt should always use a specific model or behavior.
+
+## Teams and Ownership
+
+AI Profiles support:
+
+- **Assigned User**
+- **Teams**
+
+Use this when you want profile ownership or team-level organization inside the admin UI.
+
+## Temperature Guidelines
+
+Useful starting ranges:
+
+- **0.2 - 0.4** for deterministic tasks such as summaries and extraction
+- **0.5 - 0.7** for balanced CRM assistant behavior
+- **0.7 - 0.8** for more creative drafting tasks
+
+## Related Features
+
+- [Admin Settings](admin-settings.md)
+- [AI Prompts](ai-prompts.md)
+- [AI Chat Panel](ai-chat.md)
+- [AI Summary Panel](ai-summary.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/ai-prompts.md b/docs/espocrm-extensions/espocrm-ai/features/ai-prompts.md
index 44598c6da..183a40397 100644
--- a/docs/espocrm-extensions/espocrm-ai/features/ai-prompts.md
+++ b/docs/espocrm-extensions/espocrm-ai/features/ai-prompts.md
@@ -1,55 +1,145 @@
# AI Prompts
-AI Prompts is a feature of Ebla AI that allows users to create and manage AI prompts. AI prompts are used as templates
-of prompts.
+AI Prompts are reusable prompt templates stored in EspoCRM. They can be used by several Ebla AI features, including quick field generation, custom prompt dialogs, email translation, AI Summary configuration, formula-based prompt execution, and chat prompt shortcuts.
+
+## Default Prompts
+
+On a fresh installation, Ebla AI seeds 13 prompts across general and entity-specific use cases.
+
+Examples include:
+
+- **Brief Comment**
+- **Record Summary**
+- **Follow-up Email**
+- **Meeting Preparation**
+- **Approve Reply**
+- **Decline Reply**
+- **Email Summary**
+- **Lead Qualification**
+- **Lead Introduction Email**
+- **Deal Strategy**
+- **Proposal Draft**
+- **Contact Bio**
+- **Account Review**
## Creating an AI Prompt
-1. Navigate to **Administration** -> **AI Prompts**.
+1. Navigate to **Administration → AI Prompts**.
2. Click **Create**.
-3. Enter a name for the AI prompt.
-4. Select Entity Type.
-5. Enter the prompt context.
+3. Enter:
+ - **Name**
+ - **Profile** (optional)
+ - **Entity Type** (optional)
+ - **Context**
-
+
-!!! important
+## Main Fields
- If output is not as expected, you can click on **Send** button to regenerate the output.
+### Name
-## Examples
+The label shown in prompt selectors and prompt shortcut menus.
-### Email Reply
+### Profile
-```
-Write decline reply for: {{name}}
-```
+Optional linked AI Profile. When set, features that run this prompt can use that profile as the prompt's preferred execution profile.
+
+### Entity Type
+
+Optional. Use it when the prompt is meant for a specific record type such as:
+
+- `Email`
+- `Lead`
+- `Opportunity`
+- `Contact`
+- `Account`
+
+Entity-specific prompts can also appear in the AI Chat prompt shortcut menu for that entity.
+
+### Context
+
+The actual prompt template text.
+
+## Where AI Prompts Are Used
+
+Depending on the feature, AI Prompts can be used in different ways:
+
+- **Field quick prompts** on text and varchar fields
+- **Custom AI Generate** dialogs
+- **Record AI Chat** prompt shortcut menu
+- **Email translation** default prompt
+- **AI Summary** entity-specific prompt assignment
+- **Formula** execution via `eblaAi\runPrompt`
+
+## Placeholder and Variable Support
+
+Prompt preparation supports a mix of variable styles depending on where the prompt is used.
+
+Common patterns include:
+
+- `{{name}}`
+- `{{description}}`
+- `{Contact.firstName}`
+- `{Account.name}`
+- `%all%`
+- `%value%`
+
+### `%all%`
+
+In supported prompt contexts, `%all%` inserts the full available data payload for the current record.
+
+### `%value%`
+
+In supported stream or field-generation contexts, `%value%` represents the current text value being refined.
+
+### Prompt Variable Helper
+
+The AI Prompt form includes a **Variables** helper field so you can browse and copy placeholder tokens more easily.
+
+
+
+## Prompt Scope Strategy
+
+A practical structure is:
+
+- Use **global prompts** for reusable generic instructions
+- Use **entity-specific prompts** for prompts that depend on record fields or business context
+- Link a **profile** only when the prompt needs a dedicated model or behavior
+
+## Example Prompts
+
+### Quick Comment
```
-Write approve reply for: {{name}}
+Write a concise one-line professional comment for this record.
```
-
-
-### Stream Comment
+### Lead Qualification
```
-Write a one line brief comment to ADD_COMMENT_HERE
+Analyze this lead and provide a short qualification summary.
+Highlight budget signals, urgency, likely next step, and whether the lead is Hot, Warm, or Cold.
```
-
+### Stream Comment Improvement
-### Improve Stream Comment for Case entity
+```
+Improve the following stream comment while keeping the meaning unchanged:
+%value%
```
-I have a case with the following body:
-{{{description}}}
-My reply is:
+## Best Practices
-MY_REPLAY
+- Keep prompts focused on one task
+- Use entity-specific prompts when record data matters
+- Test prompts in the relevant feature flow, not only in isolation
+- Use linked profiles only when necessary
-Improve my reply above
-```
+## Related Features
-
\ No newline at end of file
+- [AI Profiles](ai-profiles.md)
+- [AI Chat Panel](ai-chat.md)
+- [AI Summary Panel](ai-summary.md)
+- [Email Translation](email-translation.md)
+- [Formula Functions](formula.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/ai-summary.md b/docs/espocrm-extensions/espocrm-ai/features/ai-summary.md
new file mode 100644
index 000000000..ab81fcb54
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/ai-summary.md
@@ -0,0 +1,105 @@
+# AI Summary Panel
+
+The AI Summary Panel shows an AI-generated summary of the current record in the side panel area of the detail view.
+
+The panel is designed to surface a concise overview of the record using the record fields, recent activity, selected relationships, and recent related communication.
+
+The generated summary is cached in the database.
+
+
+
+## Requirements
+
+Users need:
+
+- `Ai Summary` access
+- Read access to the current record
+
+## Enabling AI Summary for an Entity
+
+1. Navigate to **Administration → Entity Manager**.
+2. Open the entity.
+3. Enable **AI Summary**.
+4. Optionally configure:
+ - **AI Summary Profile**
+ - **AI Summary Prompt**
+ - **AI Summary Include Links**
+5. Save.
+
+
+
+## First Load Behavior
+
+When the panel opens, it first checks for an existing cached summary.
+
+Current behavior:
+
+- If a cached summary exists, it is displayed immediately
+- If no cached summary exists, the panel stays empty until the user clicks the generate button
+
+## Generating and Regenerating
+
+### First Generation
+
+If no summary exists yet:
+
+1. Open the record
+2. Open the **AI Summary** panel
+3. Click **Generate Summary**
+
+### Regenerate
+
+If a summary already exists, the panel can show a regenerate control when:
+
+- The record has changed since the summary was generated
+- The current user is an administrator
+
+## Outdated Indicator
+
+The panel compares:
+
+- The summary generation time
+- The record's `modifiedAt` timestamp
+
+If the record was modified after the summary was generated, the panel marks the summary as **outdated**.
+
+
+## What Data Is Included in the Summary Context
+
+The current implementation can include:
+
+- Readable record fields
+- Assigned user
+- Selected related records from **AI Summary Include Links**
+- Recent stream items
+- Recent activities such as Meetings, Calls, and Tasks
+- Recent related emails
+- Record age and last-updated timing
+
+## Prompt and Profile Resolution
+
+Summary generation follows this priority:
+
+### Profile
+
+1. Entity-specific **AI Summary Profile**
+2. **AI Summary Default Profile**
+3. Global default AI Profile
+
+### Prompt
+
+1. Entity-specific **AI Summary Prompt**
+2. Admin-level fallback summary prompt if configured
+3. Built-in default summary prompt
+
+## Tips
+
+- Use **AI Summary Include Links** to keep related-record context focused
+- Assign a dedicated summarizer profile for more consistent output
+- Add an entity-specific summary prompt if a record type needs a special summary structure
+
+## Related Features
+
+- [AI Profiles](ai-profiles.md)
+- [AI Prompts](ai-prompts.md)
+- [AI Chat Panel](ai-chat.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/email-analysis.md b/docs/espocrm-extensions/espocrm-ai/features/email-analysis.md
new file mode 100644
index 000000000..7b725db76
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/email-analysis.md
@@ -0,0 +1,66 @@
+# Email Analysis Panel
+
+The Email Analysis panel appears on Email detail views and shows an AI-generated breakdown of the email thread.
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- Read access to Email
+- A configured default AI provider
+
+## How It Loads
+
+When the panel opens, it first checks for an existing cached analysis.
+
+Current behavior:
+
+- If a cached analysis exists, it is displayed immediately
+- If no cached analysis exists, the panel stays empty until the user clicks the Analyze Email button
+
+
+
+## Sections Shown in the Panel
+
+The panel currently shows up to four sections:
+
+### Summary
+
+A concise overview of the thread.
+
+### Action Items
+
+Structured action items extracted from the conversation.
+
+### Suggested Reply
+
+A ready-to-edit reply draft with:
+
+- **Use Reply** opens the compose modal with the suggested reply inserted above the original thread
+- **Copy**
+
+### Suggested Actions
+
+Suggested CRM actions presented as clickable cards, such as:
+
+- Create a related record
+- Update a related record
+- Post a note to the stream
+
+## What It Analyzes
+
+The analysis is based on the full thread context, not just the currently opened email body.
+
+## Re-analyzing
+
+Use the refresh icon in the panel header when:
+
+- A new reply has arrived
+- The thread changed
+- You want to regenerate the analysis
+
+## Related Features
+
+- [AI Email Composer](email-compose.md)
+- [Email Reply](email-reply.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/email-composer.md b/docs/espocrm-extensions/espocrm-ai/features/email-composer.md
new file mode 100644
index 000000000..1895f8384
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/email-composer.md
@@ -0,0 +1,88 @@
+# Email Composer AI Toolbar
+
+The Email Composer AI Toolbar adds AI actions directly inside the email editor for compose and reply workflows.
+
+In the current UI, the toolbar exposes three main actions:
+
+- **AI Draft**
+- **AI Reply**
+- **AI Polish**
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- `Ai Email Composer` access
+- A configured default AI provider
+
+The buttons can appear in both HTML and plain-text composer modes.
+
+
+
+## AI Draft
+
+**AI Draft** is the guided drafting flow for writing a new email from scratch.
+
+1. Click **AI Draft**.
+2. Enter what the email should be about.
+3. Optionally choose:
+ - **Tone**
+ - **Length**
+4. Click **Generate**.
+5. Review the generated preview.
+6. Click **Use This** to insert it into the editor.
+
+
+
+## AI Reply
+
+**AI Reply** generates a reply directly from the current email context.
+
+Current behavior:
+
+- No prompt dialog is shown
+- The action reads the current body and sender context
+- The generated reply is inserted above the existing thread
+
+This makes it useful for quick first-pass replies.
+
+## AI Polish
+
+**AI Polish** improves the user's draft text.
+
+Important behavior:
+
+- It rewrites only the draft portion
+- It does not rewrite the quoted thread below the reply
+- The quoted thread is preserved and re-appended automatically
+
+## Undo
+
+The composer keeps an undo stack for AI actions.
+
+Current behavior:
+
+- The previous body is stored before each successful AI action
+- Undo works across draft, reply, and polish
+- Undo is session-only and is not saved across refreshes
+
+## Plain-Text Mode
+
+When the email is not HTML, Ebla AI adds a small button row above the textarea with the same main actions:
+
+- **AI Draft**
+- **AI Reply**
+- **AI Polish**
+- **Undo**
+
+## Notes
+
+- The language used by generated output follows the resolved user or system language context
+- The profile used is the configured **AI Email Composer Default Profile** when set
+
+## Related Features
+
+- [Email Reply](email-reply.md)
+- [Email Translation](email-translation.md)
+- [AI Profiles](ai-profiles.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/email-reply.md b/docs/espocrm-extensions/espocrm-ai/features/email-reply.md
deleted file mode 100644
index 623458167..000000000
--- a/docs/espocrm-extensions/espocrm-ai/features/email-reply.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Email Reply
-
-By using this feature you can generate and refine a proper email reply. The AI will generate a reply based on the
-context and the prompt you provide.
-
-## Creating an Email Reply
-
-1. Navigate to the Email you want to reply to it.
-2. Click **Reply**.
-
- 
-
-3. Click **AI Generate**.
-
- 
-
-4. Select Profile "Email Reply Assistant".
-5. Enter the prompt context or select it from predefined prompts.
-
- 
-
-6. Click **Send**.
-7. The AI will generate a reply based on the context and the prompt you provided.
- - You can Press **Insert** to insert the generated reply into the email body.
- - You can Press **Copy** to copy the generated reply to the clipboard.
-
-!!! important
-
- If output is not as expected, you can click on **Send** button to regenerate the output.
\ No newline at end of file
diff --git a/docs/espocrm-extensions/espocrm-ai/features/email-template-generator.md b/docs/espocrm-extensions/espocrm-ai/features/email-template-generator.md
new file mode 100644
index 000000000..45ef31027
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/email-template-generator.md
@@ -0,0 +1,82 @@
+# AI Email Template Generator
+
+This page covers the AI generation flow inside the Email Template form itself.
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- Create access to `EmailTemplate`
+- A configured default AI provider
+
+## Where to Find It
+
+1. Open an Email Template create or edit form.
+2. Click the **AI Generate** button in the form dropdown list.
+
+
+
+OR
+
+1. Open **Email Templates**.
+2. Click **Generate Email Template** in the list view.
+
+## Modal Behavior
+
+The form-level generator opens the same core generation modal, but it respects the current template form state.
+
+Current behavior:
+
+- It starts with the current template entity type when available
+- It respects the template `Is HTML` setting
+- It does not expose a profile selector in the current UI
+
+## What Gets Filled
+
+After you click **Accept**, the form is updated with:
+
+- **Name** if it is currently empty
+- **Subject**
+- **Body**
+
+For plain-text templates, the generated content is applied as plain body text.
+
+For HTML templates, the generated HTML is applied to the WYSIWYG body field.
+
+
+
+## HTML vs Plain Text
+
+### HTML Template
+
+When the template is HTML:
+
+- The style selector is shown in the modal
+- The preview is rendered as HTML
+- The accepted output fills the HTML body
+
+### Plain-Text Template
+
+When the template is not HTML:
+
+- The style selector is hidden
+- The output is treated as plain text
+
+## Body Field AI Toolbar
+
+The Email Template body field also has its own lightweight AI refinement toolbar.
+
+Current actions:
+
+- **Improve**
+- **Fix Grammar**
+- **Make Shorter**
+
+
+
+## Related Features
+
+- [Email Template Generatior](email-template-generator.md)
+- [AI Prompts](ai-prompts.md)
+- [AI Profiles](ai-profiles.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/email-translation.md b/docs/espocrm-extensions/espocrm-ai/features/email-translation.md
new file mode 100644
index 000000000..b752a7f5a
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/email-translation.md
@@ -0,0 +1,66 @@
+# Email Translation
+
+Email Translation translates an email into the current user's language using AI.
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- `Ai Email Composer` access
+- Read access to Email
+- A configured default AI provider
+
+Administrators also need:
+
+- **Enable Email Translate** turned on in **AI Settings -> Translate**
+- A configured **AI Email Translate Default Prompt**
+
+## Translating an Email
+
+1. Open an Email.
+2. Click **Translate**.
+3. Wait for the translation to complete.
+4. Review the translated text in the modal.
+5. Click **Copy** if needed.
+
+
+
+
+## Target Language Resolution
+
+The target language is resolved automatically from:
+
+1. The user's language preference
+2. The system default language if the user has no language preference
+
+## Important Clarification
+
+`AI Translate Languages` in AI Settings does not control the target language for email translation.
+
+That setting is used for field and stream translation menus.
+
+Email translation instead uses the user's resolved CRM language.
+
+## Prompt Placeholders
+
+The email translation prompt can use:
+
+- `{{language}}`
+- `{{subject}}`
+- `{{bodyPlain}}`
+- `{{body}}`
+
+This makes it possible to create translation prompts that preserve tone or format.
+
+## Optional Translation Profile
+
+You can assign **AI Email Translate Default Profile** if you want translations to use a dedicated provider or model.
+
+If no translation profile is assigned, the feature falls back to the normal default profile behavior.
+
+## Related Features
+
+- [AI Prompts](ai-prompts.md)
+- [AI Profiles](ai-profiles.md)
+- [Email Reply](email-reply.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/field-text-generation.md b/docs/espocrm-extensions/espocrm-ai/features/field-text-generation.md
index 248737c34..7bf5052ea 100644
--- a/docs/espocrm-extensions/espocrm-ai/features/field-text-generation.md
+++ b/docs/espocrm-extensions/espocrm-ai/features/field-text-generation.md
@@ -1,33 +1,143 @@
# Field Text Generation
-By using this feature you can generate text for a field based on the context you provide.
+Field Text Generation adds AI actions directly to supported editable text fields.
-## Enable Field Text Generation
+It can generate new text, improve existing wording, shorten or expand content, translate it, or rewrite it in a selected tone.
-1. Navigate to Administration -> Entity Manager -> {Scope} -> fields -> {field}.
-2. Check **Enable AI text generation** option.
-3. (Optional) Select predefined prompt to enable Quick Text Generation.
+## Requirements
- 
+Users need:
+- `Ai` access
+- `Ai Field Action` access
+- A configured default AI provider
+
+The field itself must also have **Enable AI text generation** enabled in Entity Manager.
+
+## Enabling It for a Field
+
+1. Navigate to **Administration -> Entity Manager -> {Entity} -> Fields -> {Field}**.
+2. Enable **AI text generation**.
+3. Optionally choose an **AI Prompt** for quick generation.
4. Save.
-## Generate Text
+
+
+## Supported Field Types
+
+The current UI supports:
+
+- `text`
+- `varchar`
+- `wysiwyg`
+
+Each field type has a slightly different action set.
+
+## Text Fields
+
+When editing a `text` field, the UI shows:
+
+- A dropdown AI actions button
+- A separate **Custom Prompt** button
+
+Available actions:
+
+- **Generate from Context**
+- **Improve Writing**
+- **Fix Grammar**
+- **Make Shorter**
+- **Make Longer**
+- **Adjust Tone**
+- **Translate** or **Translate To**
+- Quick prompt action when an AI Prompt is assigned
+- **Custom Prompt**
+- **Undo Last Change**
+
+
+
+
+## Varchar Fields
+
+`varchar` fields use the same pattern as `text` fields, with one important difference:
+
+- `varchar` fields do not show **Make Longer**
+
+This keeps the output better aligned with shorter single-line field usage.
+
+## WYSIWYG Fields
+
+WYSIWYG fields add AI actions directly into the Summernote toolbar.
+
+Available actions:
+
+- **Undo**
+- **Improve Writing**
+- **Fix Grammar**
+- **Make Shorter**
+- **Make Longer**
+- **Adjust Tone**
+- **Custom Prompt**
+
+
+
+## Quick Prompt vs Custom Prompt
+
+If a field has an AI Prompt assigned in Entity Manager:
+
+- The prompt appears as a quick action in the field menu
+- Selecting it runs the prepared prompt immediately against the current record context
+
+The **Custom Prompt** button opens the general AI Generate modal, where the user can:
+
+- Select a prompt
+- Write their own prompt
+- Choose additional fields when needed
+- Review the output before inserting it
+
+## Translation Behavior
+
+Field translation uses the languages configured in **Administration -> AI Settings -> Translate -> AI Translate Languages**.
+
+Current behavior:
+
+- If one language is configured, the menu shows **Translate**
+- If multiple languages are configured, the menu shows **Translate To** with one entry per language
+
+## Adjust Tone
+
+Available tones:
+
+- **Formal**
+- **Casual**
+- **Friendly**
+- **Professional**
+- **Empathetic**
+- **Urgent**
+- **Concise**
+
+The selected tone is applied immediately to the current field content.
+
+## Undo Stack
+
+Every successful AI action stores the previous value in a session-only undo stack.
+
+Current behavior:
-1. Navigate to the record view of the entity.
-2. Click on field edit icon.
-3. Click on **Generate** icon button.
+- Undo appears only after the first successful AI action
+- Multiple undo steps are supported
+- The undo count is shown for text and varchar fields
+- Undo history is not preserved across page refreshes
- 
- 
-4. If you have predefined prompt selected, the text will be generated automatically, otherwise AI Generate Modal will be
- appearing.
-5. Enter prompt text or select predefined prompt and click send.
+## Tips
- 
+- Use quick prompts for repeatable tasks on the same field
+- Use custom prompts when you need record-specific instructions
+- Translate after refining the content if you want the best final wording
+- Review generated output before saving, especially on required or customer-facing fields
-6. Click Insert to insert generated text into field.
+## Related Features
-!!! important
+- [AI Prompts](ai-prompts.md)
+- [Stream Comment](stream-comment.md)
+- [Email Composer AI Toolbar](email-composer.md)
- If output is not as expected, you can click on **Send** button to regenerate the output.
\ No newline at end of file
diff --git a/docs/espocrm-extensions/espocrm-ai/features/formula.md b/docs/espocrm-extensions/espocrm-ai/features/formula.md
index 421343ebc..16811bd06 100644
--- a/docs/espocrm-extensions/espocrm-ai/features/formula.md
+++ b/docs/espocrm-extensions/espocrm-ai/features/formula.md
@@ -1,32 +1,219 @@
# Formula
-The Formula feature in Ebla AI allows you to create custom formula functions that can be used in various parts of the
-CRM. These functions can be used to perform calculations, manipulate data, and automate tasks. Which enables you to
-create complex and intelligent formulas that can be used to enhance your CRM operations.
+Ebla AI adds AI-oriented formula functions that can be used in workflows, before-save formulas, and other automation scenarios inside EspoCRM.
-## Using Formula
+## Access Control
-Format of function use: `eblaAi\textGenerate([propmt], profileId)`.
+To use these functions, the user or process context must have access to the **AiFormula** scope.
-!!! example
+## Available Formula Functions
- ```
- $prompt = string\concatenate('Calculate score of this profile,',
- ' name is: ', name,
- ' email is: ', emailAddress,
- ' industry is: ', industry,
- ' source is: ' , source,
- ' country is: ' , addressCountry,
- '. Provide result as number between 0-4 without explainations'
- );
-
- $profileId = '65d6f98d3d0f9f5f9';
-
- score = eblaAi\textGenerate($prompt, $profileId);
- ```
+The current build exposes the following functions:
-`Output Example: Calculate score of this profile, name is: Marry Coch email is: marry@gmail.com industry is: Banking source is: Web Site country is: Germany. Provide result as number between 0-4 without explainations`
+- `eblaAi\textGenerate`
+- `eblaAi\runPrompt`
+- `eblaAi\getPrompt`
+- `eblaAi\analyzeImage`
+- `eblaAi\generateImage`
+- `eblaAi\generateSpeech`
-!!! important
+---
- If output is not as expected, you can click on **Send** button to regenerate the output.
\ No newline at end of file
+## eblaAi\textGenerate
+
+Generates text from a prompt using the AI service.
+
+### Syntax
+
+```
+eblaAi\textGenerate(PROMPT, PROFILE_ID)
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `PROMPT` | The prompt text to send to AI |
+| `PROFILE_ID` | Optional AI Profile ID |
+
+### Example
+
+```text
+$prompt = string\concatenate(
+ 'Create a short lead summary for: ',
+ name,
+ ', industry: ',
+ industry,
+ ', source: ',
+ source
+);
+
+description = eblaAi\textGenerate($prompt, $profileId);
+```
+
+---
+
+## eblaAi\runPrompt
+
+Runs a saved **AI Prompt** by ID. If the prompt is linked to a profile, that profile can be used during execution.
+
+### Syntax
+
+```
+eblaAi\runPrompt(PROMPT_ID)
+```
+
+### Example
+
+```text
+notes = eblaAi\runPrompt('65d6f98d3d0f9f5f9');
+```
+
+### Notes
+
+- The current entity is used as the target context when the formula runs on a saved record
+- This is a practical way to reuse prompt templates in formulas
+
+---
+
+## eblaAi\getPrompt
+
+Returns a rendered prompt string from a saved prompt template so it can be reused in formula logic.
+
+### Syntax
+
+```
+eblaAi\getPrompt(PROMPT_ID)
+```
+
+or
+
+```
+eblaAi\getPrompt(PROMPT_ID, SCOPE, RECORD_ID)
+```
+
+### Example
+
+```text
+$prompt = eblaAi\getPrompt($promptId, 'Contact', contactId);
+description = eblaAi\textGenerate($prompt, $profileId);
+```
+
+### Notes
+
+- This function returns prompt text only
+- It does not call the AI by itself
+- If the prompt cannot be resolved, the function returns an empty string
+
+---
+
+## eblaAi\analyzeImage
+
+Analyzes an image attachment using a vision-capable provider and returns the result as text.
+
+### Syntax
+
+```
+eblaAi\analyzeImage(ATTACHMENT_ID, PROMPT, PROFILE_ID)
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `ATTACHMENT_ID` | Attachment record ID |
+| `PROMPT` | Optional custom analysis prompt |
+| `PROFILE_ID` | Optional vision-capable AI Profile |
+
+### Example
+
+```text
+$result = eblaAi\analyzeImage(contractScanId, 'Extract the contract dates.');
+```
+
+### Notes
+
+- Returns a string
+- On failure, returns a string starting with `Error:`
+
+---
+
+## eblaAi\generateImage
+
+Generates an image and saves it as an Attachment record.
+
+### Syntax
+
+```
+eblaAi\generateImage(PROMPT, SIZE, PROFILE_ID)
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `PROMPT` | Image description |
+| `SIZE` | `square`, `landscape`, or `portrait` |
+| `PROFILE_ID` | Optional AI Profile |
+
+### Example
+
+```text
+photoId = eblaAi\generateImage(
+ 'Professional product image on a white background',
+ 'square',
+ $profileId
+);
+```
+
+### Provider Support
+
+Image generation is currently supported by:
+
+- **OpenAI**
+- **Google Gemini**
+
+---
+
+## eblaAi\generateSpeech
+
+Converts text to speech and saves the result as an Attachment record.
+
+### Syntax
+
+```
+eblaAi\generateSpeech(TEXT, VOICE, SPEED, PROFILE_ID)
+```
+
+### Parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `TEXT` | Text to convert |
+| `VOICE` | Optional provider-specific voice |
+| `SPEED` | Optional speed multiplier |
+| `PROFILE_ID` | Optional AI Profile |
+
+### Example
+
+```text
+$audioId = eblaAi\generateSpeech(
+ 'Welcome to our company.',
+ 'nova',
+ 1.0,
+ $profileId
+);
+```
+
+### Notes
+
+- OpenAI produces MP3 output
+- Gemini produces WAV output
+- Maximum text length is limited by the API endpoint used by the service
+
+## Related Features
+
+- [AI Prompts](ai-prompts.md)
+- [Image Analysis](image-analysis.md)
+- [Image Generation](image-generation.md)
+- [Voice Generation](voice-generation.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/image-analysis.md b/docs/espocrm-extensions/espocrm-ai/features/image-analysis.md
new file mode 100644
index 000000000..f47e152ea
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/image-analysis.md
@@ -0,0 +1,85 @@
+# Image Analysis
+
+Image Analysis lets users ask AI questions about uploaded images directly inside EspoCRM.
+
+It is intended for image-based attachments such as screenshots, scans, photos, and similar visual files.
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- `Ai Vision` access
+- A configured default AI provider
+- A vision-capable provider or profile
+
+## Where It Appears
+
+The current implementation exposes analysis in two places:
+
+- On `Image` fields in detail view
+- In the image preview modal
+
+
+
+## Using Image Analysis
+
+1. Open a record with an image field.
+2. Click **Analyze**.
+3. Enter an optional prompt.
+4. Click **Analyze** in the modal.
+5. Review the result.
+6. Use **Copy** if you want to reuse the output elsewhere.
+
+
+
+## Supported File Types
+
+The backend accepts image attachments only.
+
+Supported formats:
+
+- `JPEG`
+- `PNG`
+- `GIF`
+- `WebP`
+
+Maximum file size:
+
+- `10 MB`
+
+## Prompt Usage
+
+If you leave the prompt empty, the feature uses a default general image-analysis prompt.
+
+Examples of useful prompts:
+
+- "Extract the visible text from this image."
+- "Summarize the key information in this screenshot."
+- "Does this image contain a signature?"
+- "List the line items visible in this receipt."
+
+## Formula Support
+
+Image analysis is also available in formula:
+
+```text
+eblaAi\analyzeImage(ATTACHMENT_ID, PROMPT, PROFILE_ID)
+```
+
+It returns the analysis text, or an error string starting with `Error:`.
+
+See [Formula](formula.md) for examples.
+
+## Limitations
+
+- Only image files are supported
+- PDF and document attachments are not analyzed by this feature
+- Results depend on image quality and model capability
+- A text-only provider or model will fail for vision requests
+
+## Related Features
+
+- [Image Generation](image-generation.md)
+- [Formula](formula.md)
+- [Access Control](access-control.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/image-generation.md b/docs/espocrm-extensions/espocrm-ai/features/image-generation.md
new file mode 100644
index 000000000..8e99ff714
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/image-generation.md
@@ -0,0 +1,92 @@
+# AI Image Generation
+
+AI Image Generation creates new images from a text prompt and saves them as EspoCRM attachments.
+
+The generated image can then be attached to an `Image` field or appended to an `Attachment Multiple` field.
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- `Ai Vision` access
+- A configured default AI provider
+- A provider or profile that supports image generation
+
+## Enabling It on a Field
+
+Image generation is opt-in per field.
+
+1. Navigate to **Administration -> Entity Manager -> {Entity} -> Fields -> {Field}**.
+2. Enable **AI Image Generation**.
+3. Save.
+
+This works for:
+
+- `Image`
+- `Attachment Multiple`
+
+## Where the Button Appears
+
+In the current UI:
+
+- `Image` fields show the button in edit mode
+- `Attachment Multiple` fields show an icon button in edit mode
+
+
+
+## Using Image Generation
+
+1. Open the record in edit mode.
+2. Click the image-generation button.
+3. Enter a prompt describing the image you want.
+4. Select a size.
+5. Click **Generate**.
+6. Review the preview.
+7. Click **Use Image**.
+
+
+
+## Available Sizes
+
+The current modal offers:
+
+- `Square`
+- `Landscape`
+- `Portrait`
+
+Provider-specific output dimensions depend on the selected provider and model.
+
+## Field Behavior
+
+### Image Field
+
+For a single image field, the generated attachment replaces the current image reference.
+
+### Attachment-Multiple Field
+
+For an attachment-multiple field, the generated image is appended to the existing attachment list.
+
+## Formula Support
+
+Image generation is also available in formula:
+
+```text
+eblaAi\generateImage(PROMPT, SIZE, PROFILE_ID)
+```
+
+The function returns the generated attachment ID.
+
+See [Formula](formula.md).
+
+## Notes
+
+- Anthropic and Ollama do not provide image generation in the current extension flows
+- A provider that supports vision is not always the same as one that supports image generation, so choose the profile carefully
+- Prompt quality has a large effect on output quality
+
+## Related Features
+
+- [Image Analysis](image-analysis.md)
+- [Formula](formula.md)
+- [AI Profiles](ai-profiles.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/pdf-template.md b/docs/espocrm-extensions/espocrm-ai/features/pdf-template.md
new file mode 100644
index 000000000..cd067f31a
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/pdf-template.md
@@ -0,0 +1,78 @@
+# AI PDF Template Generation
+
+The AI PDF Template Generator creates EspoCRM PDF templates from a plain-language description. It generates a template name and a full HTML body designed for PDF rendering, including entity placeholders where appropriate.
+
+## Where to Find It
+
+The feature is available from the **PDF Template** list view.
+
+1. Navigate to **Administration** → **PDF Templates**.
+2. Click **Generate PDF Template** in the list view header.
+
+## How It Works
+
+1. Click **Generate PDF Template**.
+2. A modal opens with:
+ - **Entity Type** - optional; used to expose the correct placeholders
+ - **Description** - describe the template you want to generate
+3. Click **Generate**.
+4. The AI returns:
+ - A template **Name**
+ - A complete HTML **Body**
+5. Review the live preview in the modal.
+6. Click **Create Template**.
+7. The standard EspoCRM PDF Template create form opens with the AI-generated content prefilled.
+8. Review the result and save.
+
+
+
+## Placeholder Support
+
+When you choose an **Entity Type**, the generator uses the available fields of that entity to build the placeholder list.
+
+Examples:
+
+- `{name}`
+- `{assignedUserName}`
+- `{accountName}`
+- `{today}`
+- `{currentYear}`
+
+The AI is instructed to use only supported placeholders and keep them in EspoCRM's normal `{placeholder}` format.
+
+## Output Format
+
+The generated PDF template body is:
+
+- HTML-based
+- Intended for PDF rendering
+- Structured for print-friendly layouts
+- Generated without wrapping ``, ``, or `` tags
+
+Typical output includes:
+
+- A document header
+- A main content section
+- Tables or structured blocks where useful
+- A footer area
+
+## Tips for Better Results
+
+- Mention the document purpose clearly, such as invoice, quote, proposal, statement, or certificate.
+- Mention sections you want included, for example totals, customer details, payment instructions, or approval blocks.
+- Select the correct entity type so the AI can use the proper placeholders.
+
+!!! tip
+
+ A more specific description usually gives a much better result than a short generic phrase.
+
+## Notes
+
+- The AI does not save anything automatically.
+- The generated template is reviewed in the normal create form before you save.
+- If the entity type is selected, the create form is opened with that entity context and the AI-generated body applied automatically.
+
+## Related Features
+
+- [AI Email Template Generatior](email-template-generator.md) - Generate email templates with placeholders
+- [AI Profiles](ai-profiles.md) - Configure provider, model, and behavior
diff --git a/docs/espocrm-extensions/espocrm-ai/features/sandbox.md b/docs/espocrm-extensions/espocrm-ai/features/sandbox.md
index 3d6a8ef01..74178935b 100644
--- a/docs/espocrm-extensions/espocrm-ai/features/sandbox.md
+++ b/docs/espocrm-extensions/espocrm-ai/features/sandbox.md
@@ -1,15 +1,94 @@
# AI Sandbox
-The AI Sandbox is a feature of Ebla AI that allows users to test and experiment with AI prompts and prompts. The AI
-Sandbox is a safe environment where you can test your AI prompts and formula functions without affecting your CRM data.
+The AI Sandbox is an administrator-facing testing page for prompts and record-aware AI instructions. It lets you experiment with prompts, profiles, and optional tool-enabled execution without changing production data or normal user workflows.
-## Using AI Sandbox
+
-1. Navigate to **Administration** -> **AI Sandbox**.
-2. Select **Entity Type** / **Entity** / **Profile**.
-3. Enter the prompt context.
-4. Click **Send**.
+## Where to Find It
-___
+1. Navigate to **Administration**.
+2. Open **AI Sandbox** from the Ebla AI administration section.
-
\ No newline at end of file
+## What the Sandbox Is For
+
+Use the sandbox when you want to:
+
+- Test a prompt against a real record
+- Try a specific AI Profile
+- Compare plain prompt execution with tool-enabled execution
+- Inspect which tools were used during a tool-enabled request
+
+## Sandbox Fields
+
+The page includes:
+
+- **Entity Type**
+- **Target Record**
+- **Profile**
+- **Enable Tools**
+- **Prompt**
+- **Output**
+- **Error**
+- **Tools Used**
+
+## Using the Sandbox
+
+1. Select an **Entity Type**.
+2. Optionally choose a **Target Record**.
+3. Optionally choose an **AI Profile**.
+4. Enter your prompt.
+5. Decide whether to enable **Tools**.
+6. Run the request.
+
+!!! note
+
+ The available **Target Record** options depend on the selected **Entity Type**.
+
+## Run Modes
+
+### Standard Mode
+
+With **Enable Tools** turned off, the sandbox sends the prompt through the generic AI execution flow.
+
+This is useful for:
+
+- Prompt drafting
+- Testing profile behavior
+- Evaluating output tone and structure
+
+### Tool-Enabled Mode
+
+With **Enable Tools** turned on, the sandbox uses the AI Chat tool-calling flow instead of plain prompt execution.
+
+This is useful for:
+
+- Testing CRM-aware requests
+- Validating tool-calling behavior
+- Seeing which tools were used and how many iterations were required
+
+## Output Areas
+
+### Output
+
+Displays the AI's final text result.
+
+### Error
+
+Shows validation or request errors when the request fails.
+
+### Tools Used
+
+In tool-enabled mode, this section shows:
+
+- The tools called
+- Their arguments
+- Shortened result previews
+- Iteration count
+- Input and output token totals
+
+## Related Features
+
+- [AI Admin Assistant](admin-assistant.md)
+- [AI Profiles](ai-profiles.md)
+- [AI Prompts](ai-prompts.md)
+- [AI Chat Panel](ai-chat.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/smart-paste.md b/docs/espocrm-extensions/espocrm-ai/features/smart-paste.md
new file mode 100644
index 000000000..e5dc64cab
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/smart-paste.md
@@ -0,0 +1,126 @@
+# Smart Paste
+
+Smart Paste reads copied text from the clipboard, extracts structured values with AI, and fills the matching EspoCRM fields for the target entity.
+
+It is useful for turning business cards, email signatures, copied messages, meeting notes, or other semi-structured text into CRM data quickly.
+
+## Requirements
+
+Users need:
+
+- `Ai` access
+- `Ai Smart Paste` access
+- A configured default AI provider
+- Create access for new-record Smart Paste
+
+Administrators also need to configure visibility in **Administration -> AI Settings -> General -> Smart Paste Scopes**.
+
+## Where Smart Paste Appears
+
+The current build can show Smart Paste in three places:
+
+- Main list view headers
+- Relationship panel lists
+- New-record forms
+
+
+
+
+## Current Workflow
+
+Smart Paste does not open a text-entry modal in the current implementation.
+
+Instead, the feature works like this:
+
+1. Copy text to your clipboard.
+2. Click **Smart Paste**.
+3. Confirm that the feature should read the clipboard.
+4. Ebla AI reads the clipboard text and analyzes it against the target entity fields.
+5. The result is applied directly to the form, or used to open a pre-filled create form.
+
+## Behavior by Location
+
+### Main List Views
+
+From a main list page, Smart Paste:
+
+1. Reads clipboard text
+2. Extracts values for the current entity type
+3. Opens the standard create form with the extracted values pre-filled
+
+### Relationship Panels
+
+From a relationship panel list, Smart Paste follows the same flow:
+
+1. Reads clipboard text
+2. Extracts values for the panel entity type
+3. Opens a create form with pre-filled values
+
+### New-Record Forms
+
+When used inside a new-record form, Smart Paste applies the extracted values directly into the current unsaved record instead of opening another form.
+
+There is also a keyboard shortcut:
+
+- `Ctrl+Alt+V`
+
+## What Smart Paste Can Fill
+
+Smart Paste works best with standard storable fields such as:
+
+- Text and varchar fields
+- Email and phone fields
+- Numeric fields
+- Date and datetime fields
+- Enum and boolean fields
+- Address-style fields
+
+The field labels and tooltips are used as part of the AI context, so clear field naming improves extraction quality.
+
+## What Smart Paste Does Not Fill Well
+
+The current implementation is not intended for:
+
+- File uploads
+- Complex relationship linking
+- Advanced multi-record logic
+- Guaranteed exact matching for ambiguous input
+
+You should still review the result before saving.
+
+## Example
+
+Copied text:
+
+```text
+John Smith
+Senior Sales Manager
+Acme Corporation
+john.smith@acme.com
++1 (555) 123-4567
+123 Business Ave, Suite 100
+New York, NY 10001
+```
+
+Typical result:
+
+- First name
+- Last name
+- Job title
+- Company
+- Email
+- Phone
+- Address details
+
+## Tips
+
+- Copy the cleanest version of the source text you can
+- Semi-structured input usually performs better than noisy paragraphs
+- Add helpful field tooltips in Entity Manager for better matching
+- Review enum, relationship, and date values carefully before saving
+
+## Related Features
+
+- [AI Create](ai-create.md)
+- [Field Text Generation](field-text-generation.md)
+- [AI Profiles](ai-profiles.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/stream-comment.md b/docs/espocrm-extensions/espocrm-ai/features/stream-comment.md
index 1a55761c2..d7155de07 100644
--- a/docs/espocrm-extensions/espocrm-ai/features/stream-comment.md
+++ b/docs/espocrm-extensions/espocrm-ai/features/stream-comment.md
@@ -1,21 +1,84 @@
-# Stream Comment Reply
+# Stream Comment
-By using this feature you can generate and refine a proper comment for the stream. The AI will generate a comment based
-on the previous comments and the prompt you provide.
+The Stream Comment feature adds AI writing actions to the record stream post box.
-## Creating a Stream Comment Reply
+It helps users refine, translate, or rewrite comments before posting them to the stream.
-1. Navigate to the Record you want to comment on it.
-2. Click on Stream section on **Write your comment here**.
-3. Press on the bolt icon button.
+## Requirements
- 
+Users need:
-4. Select Profile. (Optional)
-5. Enter the prompt context or select it from predefined prompts.
-6. Click **Send**.
-7. If output is good, you can click on **Insert** to add the comment.
+- `Ai` access
+- `Ai Field Action` access
+- A configured default AI provider
-!!! important
+## Using AI in the Stream
- If output is not as expected, you can click on **Send** button to regenerate the output.
\ No newline at end of file
+1. Open a record detail view.
+2. Go to the **Stream** panel.
+3. Type a draft comment in the post box.
+4. Click the AI button beside the post controls.
+5. Choose the action you want.
+6. Review the updated text in the comment box.
+7. Click **Post** when ready.
+
+
+
+## Available Actions
+
+- **Improve Writing**
+- **Fix Grammar**
+- **Make Shorter**
+- **Make Longer**
+- **Adjust Tone**
+- **Translate** or **Translate To**
+- **Custom Prompt...**
+- **Undo Last Change**
+
+## Adjust Tone
+
+The tone menu offers:
+
+- **Formal**
+- **Casual**
+- **Friendly**
+- **Professional**
+- **Empathetic**
+- **Urgent**
+- **Concise**
+
+## Translation Behavior
+
+Stream translation uses the same language list configured in **AI Settings -> Translate -> AI Translate Languages**.
+
+Current behavior:
+
+- One configured language shows a single **Translate** action
+- Multiple configured languages show **Translate To**
+
+## Undo Behavior
+
+After the first successful AI action, **Undo Last Change** appears at the top of the menu.
+
+Undo is:
+
+- Session-only
+- Multi-step
+- Limited to the current unsent comment draft
+
+## Custom Prompt
+
+The **Custom Prompt...** action opens the general AI Generate modal with the current comment text passed in as context.
+
+This is useful when the built-in improve/grammar/shorter/longer actions are not specific enough.
+
+## Notes
+
+- Stream AI works on the draft text currently in the comment box
+- The generated text is not posted automatically
+- You can keep refining the draft before posting
+
+## Related Features
+
+- [Field Text Generation](field-text-generation.md)
+- [AI Prompts](ai-prompts.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/token-usage.md b/docs/espocrm-extensions/espocrm-ai/features/token-usage.md
new file mode 100644
index 000000000..b253658f1
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/token-usage.md
@@ -0,0 +1,95 @@
+# Token Usage Statistics
+
+Ebla AI records token usage for AI requests and exposes both aggregate and per-request visibility.
+
+## Overview
+
+The extension tracks:
+
+- Input tokens
+- Output tokens
+- Total tokens
+- Request count
+
+Daily aggregate usage is stored in `AiTokenUsage`.
+
+Per-request details are stored in `AiLog`.
+
+
+
+## Viewing Usage
+
+1. Navigate to **{{siteUrl}}/#AiTokenUsage**.
+2. Review usage by user and date.
+3. Open **AI Token Usage** when you need call-level detail.
+
+## Token Limits
+
+System-wide limits are configured in:
+
+- **Administration -> AI Settings -> Token Limits**
+
+Available settings:
+
+- **Default Token Limit**
+- **Token Limit Period**
+- **Max Tool-Call Iterations**
+
+## Per-User Override
+
+Each user record includes **AI Monthly Token Limit**.
+
+Important clarification:
+
+- The field label says **Monthly**
+- The value actually acts as the user's override for the currently configured limit period
+
+That period may be:
+
+- Daily
+- Weekly
+- Monthly
+
+Set the field to `0` to fall back to the global default.
+
+## Cache Hits and Token Usage
+
+When a request is served from the response cache:
+
+- The response is returned faster
+- No new provider call is made
+- No new tokens are consumed for that cached request
+- The call is still visible in **AI Log** as a cache hit
+
+This is especially important for repeat analysis and generation requests.
+
+## Dashlets
+
+The extension includes token-usage dashlets for dashboards.
+
+Available dashlets:
+
+- **My AI Token Usage**
+- **AI Token Usage - All Users**
+
+
+
+## AI Log Relationship
+
+Use **AI Log** together with **AI Token Usage** when you need to answer questions such as:
+
+- Which feature consumed the most tokens?
+- Was this response cached?
+- Which user triggered the request?
+- Which profile and provider were used?
+
+## Notes
+
+- Administrators are not blocked by token limits
+- Limit enforcement happens before new provider calls are made
+- Feature usage, cache behavior, and token totals are easier to audit when both **AI Log** and **AI Token Usage** are enabled in your admin workflow
+
+## Related Features
+
+- [Access Control](access-control.md)
+- [Admin Settings](admin-settings.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/features/voice-generation.md b/docs/espocrm-extensions/espocrm-ai/features/voice-generation.md
new file mode 100644
index 000000000..fa2c0a5ac
--- /dev/null
+++ b/docs/espocrm-extensions/espocrm-ai/features/voice-generation.md
@@ -0,0 +1,35 @@
+# AI Voice Generation
+
+Voice Generation is currently available as a formula capability only.
+
+## Current Availability
+
+Use cases today are mainly:
+
+- Workflow automation
+- Formula-driven generation
+- Custom integrations
+
+## Formula Support
+
+Speech generation is available through:
+
+```text
+eblaAi\generateSpeech(TEXT, VOICE, SPEED, PROFILE_ID)
+```
+
+The function creates an attachment and returns its ID.
+
+See [Formula](formula.md) for usage examples.
+
+## Provider Notes
+
+The extension includes provider-specific speech generation support for selected providers such as OpenAI and Gemini.
+
+Actual voice names and audio formats depend on the provider behind the resolved profile.
+
+## Related Features
+
+- [Formula](formula.md)
+- [AI Profiles](ai-profiles.md)
+- [Image Generation](image-generation.md)
diff --git a/docs/espocrm-extensions/espocrm-ai/index.md b/docs/espocrm-extensions/espocrm-ai/index.md
index aec9e8edc..77aa83e9b 100644
--- a/docs/espocrm-extensions/espocrm-ai/index.md
+++ b/docs/espocrm-extensions/espocrm-ai/index.md
@@ -1,18 +1,26 @@
---
icon: material/robot
title: Ebla AI - EspoCRM
-description: AI-powered automations, suggestions, formula, and smart record paste for EspoCRM. Support Ollama, Gemini, Anthropic, OpenRouter and OpenAI.
+description: AI-powered chat, summaries, prompts, smart paste, content generation, admin assistance, and provider integrations for EspoCRM.
---
# Ebla AI Documentation
## Overview
-**Ebla AI** supports both of Ollama, Gemini, Anthropic, OpenRouter and OpenAI, a step to bring the power of AI to your EspoCRM.
-Ebla AI provides a range of AI-driven features, like generating email messages, stream comments suggestions and custom formula functions.
-Enhances communication, lead management, and workflow automation.
+**Ebla AI** brings AI-assisted workflows directly into EspoCRM using **OpenAI**, **Google Gemini**, **Anthropic**, **OpenRouter**, and **Ollama**.
-## Extension video
+The extension includes:
+
+- AI Profiles and AI Prompts for reusable configuration
+- AI Chat and AI Summary panels on records
+- AI-assisted email composition, reply, translation, and analysis
+- Smart Paste and Create with AI for faster data entry
+- AI tools for text fields, stream comments, images, and speech
+- Formula functions for workflows and automations
+- Admin tools such as AI Sandbox, AI Assistant, AI Log, and token usage monitoring
+
+## Extension Video
@@ -22,11 +30,24 @@ Enhances communication, lead management, and workflow automation.
- [AI Profiles Management](features/ai-profiles.md)
- [AI Prompts Management](features/ai-prompts.md)
-- [AI Email Generated](features/email-reply.md)
-- [AI Stream Comment Generation](features/stream-comment.md)
+- [AI Admin Assistant](features/admin-assistant.md)
+- [AI Chat Panel](features/ai-chat.md)
+- [AI Summary Panel](features/ai-summary.md)
+- [AI Create from List View](features/ai-create.md)
+- [AI Smart Paste](features/smart-paste.md)
- [AI Field Text Generation](features/field-text-generation.md)
+- [AI Stream Comment Generation](features/stream-comment.md)
+- [AI Email Composer](features/email-composer.md)
+- [AI Email Analysis Panel](features/email-analysis.md)
+- [AI Email Translation](features/email-translation.md)
+- [AI Email Template Generator](features/email-template-generator.md)
+- [AI PDF Template Generation](features/pdf-template.md)
+- [AI Image Analysis](features/image-analysis.md)
+- [AI Image Generation](features/image-generation.md)
+- [AI Voice Generation (TTS)](features/voice-generation.md)
- [AI Formula Functions](features/formula.md)
- [AI Sandbox](features/sandbox.md)
+- [Token Usage & Limits](features/token-usage.md)
### Setup and Configuration
@@ -35,7 +56,8 @@ Enhances communication, lead management, and workflow automation.
- [Setup Ollama](providers/ollama-setup.md)
- [Setup Anthropic](providers/anthropic-setup.md)
- [Setup OpenRouter](providers/open-router-setup.md)
-- [Access control](features/access-control.md)
+- [Access Control](features/access-control.md)
+- [Admin Settings](features/admin-settings.md)
## ChangeLog
diff --git a/docs/espocrm-extensions/espocrm-ai/providers/anthropic-setup.md b/docs/espocrm-extensions/espocrm-ai/providers/anthropic-setup.md
index dac93c028..6d6162afe 100644
--- a/docs/espocrm-extensions/espocrm-ai/providers/anthropic-setup.md
+++ b/docs/espocrm-extensions/espocrm-ai/providers/anthropic-setup.md
@@ -15,3 +15,21 @@
3. Choose the default model you want to use.
+
+## Final Step in AI Settings
+
+After saving the integration:
+
+1. Navigate to **Administration** -> **AI Settings**.
+2. Open the **General** tab.
+3. Set **Default AI Provider** to **Anthropic**.
+4. Save.
+
+## Capability Notes
+
+Anthropic is suitable for:
+
+- Chat and text generation
+- Vision analysis on supported models
+
+It is not used by the current extension flows for image generation or speech generation.
diff --git a/docs/espocrm-extensions/espocrm-ai/providers/gemini-setup.md b/docs/espocrm-extensions/espocrm-ai/providers/gemini-setup.md
index 8a2f8e029..6d1a0a78e 100644
--- a/docs/espocrm-extensions/espocrm-ai/providers/gemini-setup.md
+++ b/docs/espocrm-extensions/espocrm-ai/providers/gemini-setup.md
@@ -15,3 +15,21 @@
3. Choose the default model you want to use.
+
+## Final Step in AI Settings
+
+After saving the integration:
+
+1. Navigate to **Administration** -> **AI Settings**.
+2. Open the **General** tab.
+3. Set **Default AI Provider** to **Gemini**.
+4. Save.
+
+## Capability Notes
+
+Gemini is commonly used in the extension for:
+
+- Chat and text generation
+- Vision analysis
+- Image generation
+- Speech generation
diff --git a/docs/espocrm-extensions/espocrm-ai/providers/ollama-setup.md b/docs/espocrm-extensions/espocrm-ai/providers/ollama-setup.md
index 08876ccc1..5b30afbd3 100644
--- a/docs/espocrm-extensions/espocrm-ai/providers/ollama-setup.md
+++ b/docs/espocrm-extensions/espocrm-ai/providers/ollama-setup.md
@@ -18,4 +18,25 @@
3. Choose the default model you want to use.
-
+
+## Final Step in AI Settings
+
+After saving the integration:
+
+1. Navigate to **Administration** -> **AI Settings**.
+2. Open the **General** tab.
+3. Set **Default AI Provider** to **Ollama**.
+4. Save.
+
+## Capability Notes
+
+Ollama is mainly useful for local text-generation and chat scenarios.
+
+Feature support depends on the model you run locally.
+
+In the current extension documentation set, Ollama should not be assumed to support:
+
+- Image generation
+- Speech generation
+
+Test the selected local model before enabling more advanced AI workflows.
diff --git a/docs/espocrm-extensions/espocrm-ai/providers/open-router-setup.md b/docs/espocrm-extensions/espocrm-ai/providers/open-router-setup.md
index 4cb8fb5b1..b93701a0a 100644
--- a/docs/espocrm-extensions/espocrm-ai/providers/open-router-setup.md
+++ b/docs/espocrm-extensions/espocrm-ai/providers/open-router-setup.md
@@ -15,3 +15,22 @@
3. Choose the default model you want to use.
+
+## Final Step in AI Settings
+
+After saving the integration:
+
+1. Navigate to **Administration** -> **AI Settings**.
+2. Open the **General** tab.
+3. Set **Default AI Provider** to **OpenRouter**.
+4. Save.
+
+## Capability Notes
+
+OpenRouter capability depends on the routed model you choose.
+
+Recommended approach:
+
+- Use it for chat and text generation first
+- Verify vision support before enabling image-analysis workflows
+- Test advanced generation features with the selected model before documenting them for end users
diff --git a/docs/espocrm-extensions/espocrm-ai/providers/openai-setup.md b/docs/espocrm-extensions/espocrm-ai/providers/openai-setup.md
index e1ccfc1c9..b90f7b5cb 100644
--- a/docs/espocrm-extensions/espocrm-ai/providers/openai-setup.md
+++ b/docs/espocrm-extensions/espocrm-ai/providers/openai-setup.md
@@ -15,3 +15,25 @@
3. Choose the default model you want to use.
+
+## Final Step in AI Settings
+
+After saving the integration:
+
+1. Navigate to **Administration** -> **AI Settings**.
+2. Open the **General** tab.
+3. Set **Default AI Provider** to **OpenAI**.
+4. Save.
+
+!!! important
+
+ Configuring the integration alone is not enough. The extension also needs a default provider selected in **AI Settings** before most AI features become available.
+
+## Capability Notes
+
+OpenAI is suitable for:
+
+- Chat and text generation
+- Vision analysis
+- Image generation
+- Speech generation
diff --git a/mkdocs.yml b/mkdocs.yml
index efdc3020d..d6e4d4c15 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -157,4 +157,4 @@ nav:
- Ebla Last Login: 'espocrm-extensions/last-login/index.md'
- Ebla Welcome: 'espocrm-extensions/welcome/index.md'
- - Ebla Internal & Public Case: 'espocrm-extensions/internal-public-case/index.md'
+ - Ebla Internal & Public Case: 'espocrm-extensions/internal-public-case/index.md'
\ No newline at end of file