docs: add docs for manager area and descriptions for CMP

Writerside/m.tree

@@ -9,12 +9,12 @@
     <toc-element topic="index.md"/>
     <toc-element topic="Glossary.md"/>
     <toc-element toc-title="Admin">
+        <toc-element topic="Prompt-Library.md"/>
         <toc-element topic="Agents.md"/>
-        <toc-element topic="Context-Providers.md"/>
         <toc-element topic="Tools.md"/>
+        <toc-element topic="Context-Providers.md"/>
     </toc-element>
     <toc-element toc-title="Configuration">
-        <toc-element topic="Prompt-Library.md"/>
         <toc-element topic="Chat.md"/>
         <toc-element topic="Configuration_Overview.md"/>
         <toc-element topic="Supported-Services.md"/>

Writerside/topics/Agents.md

@@ -1,26 +1,52 @@
 # Agents
-
-To create an agent, navigate to the Extras -> modAI -> Agents and hit `Create Agent` button.
-
-## Properties
-
-### Name
-Name of the agent, this text will show up in the modAI UI, in the agent selector.
-
-### Description
-Internal description of the agent, doesn't have any special functionality.
-
-### User Groups
-When defined, only users from those user groups will be able to use this agent. SUDO users have an access to every agent.
-
-### Enabled
-If set to `false`, the agent won't be available in the agent selector.
-
-### Model
-Name of the model this agent will use. If not specified, model from appropriate system setting will be used. 
-
-### Prompt
-Custom system prompt for this agent. Can give a specific persona to the agent, or instruct the AI how to use and combine specific tools.
-
-### Advanced Config
-Through advanced config, you can override any model setting (that you have in system settings), or add any additional parameters. The format is same as in system settings.
+## What an Agent Is
+An **Agent** is a named configuration that bundles:
+- A default **AI model** (and provider)
+- A **system prompt** that defines the Agent’s role and behavior
+- Optional **Tools** an Agent is allowed to call
+- Optional **Context Providers** an Agent can use for retrieval‑augmented generation
+- Access control and advanced execution options
+
+Agents give you consistent behavior for repeated tasks (e.g., “ContentWriter”, “Dev Helper”, “Support Agent”) and allow you to centralize configuration instead of scattering prompts and settings across individual fields.
+
+## Example Use Cases
+- A marketing‑focused writer for landing pages and blog posts
+- An SEO assistant for refining titles, meta descriptions, and schema
+- A developer-focused helper that can inspect MODX Elements or suggest code updates
+- A support or internal‑docs Agent that answers questions from indexed resources
+- 
+## Creating and Managing Agents
+From the **Agents** tab:
+- Click **Create Agent**.
+- Fill in the core settings:
+    - **Name** – Human‑friendly label shown in dropdowns and selectors.
+    - **Description** – Short explanation of what the agent is for.
+    - **Model** – The default model identifier (e.g., openai/gpt-5.1-mini, anthropic/claude-4.5-opus, google/gemini-3.0-pro, or a custom provider/model ID).
+    - **Base Prompt / System Prompt** – High‑level instructions defining the Agent’s persona, guardrails, and output style.
+- Optionally configure:
+    - **Tools** – Select which tools this agent may call.
+    - **Context Providers** – Select the providers this agent can use to pull in relevant content.
+    - **User Group / Access Rules** – Restrict visibility/use of the agent to specific MODX user groups.
+    - **Advanced Configuration** – Any JSON or structured options supported by the implementation (for example, temperature, max tokens, or provider‑specific flags).
+- Set **Enabled = Yes** to make the agent available in the modAI UI.
+- Save.
+
+Once created, the Agent appears in:
+- The Agent selector in the modAI chat modal.
+- Any UI where the ✦ button is configured to allow Agent selection.
+
+## Access Control and Permissions
+Agents can be scoped so that:
+- Only specific **user groups** can see or select them.
+- Certain Agents are reserved for administrators (e.g., ones with tools that modify templates or chunks).
+- Agents without any tools behave as “pure” chat/content Agents; those with tools can run actions on behalf of the user.
+
+When designing agents:
+- Separate **high‑risk tools** (e.g., edit or delete operations) into dedicated admin‑only agents.
+- Use more constrained, read‑only Agents for general users.
+
+## Best Practices
+- Keep each Agent focused on a single domain (e.g., “ContentWriter”, “SEO Assistant”, “Developer Helper”) instead of one catchall agent.
+- Put brand voice, tone, and formatting rules into the system prompt so results are consistent across your site.
+- Reuse the same Agent wherever possible rather than copying prompts into multiple agents.
+- Periodically review usage and refine prompts based on real outputs, feedback, and new LLM updates/options.

Writerside/topics/Context-Providers.md

@@ -1,22 +1,48 @@
 # Context Providers
 
-To be able to use context providers through agents, they have to be created and configured from this section.
-
-To create & configure context provider, navigate to the Extras -> modAI -> Context Providers and hit `Create Context Provider` button.
-
-## Properties
-
-### Context Provider Class
-Implementation of the context provider. Every context provider class can have an additional configuration that will show up in the `Config` panel on the right side. Additional context providers can be registered using plugin with `modAIOnContextProviderRegister` event.
-
-### Name
-Name of the context provider, this name has to be unique across all configured context providers.
-
-### Description
-Internal description of the context provider, doesn't have any special functionality.
-
-### Enabled
-If set to `false`, the context provider won't be available for use, even when assigned to agents.
-
-### Additional Config Options
-Every context provider class can expose a different set of additional config options. You can reference a value from system settings by using `ss:system_setting_key` format for the config option's value.
+## What a Context Provider Is
+A **Context Provider** is a component that knows how to:
+- Retrieve relevant documents or records (from MODX, a search index, or an external service).
+- Convert them into chunks of text and/or metadata suitable for AI consumption.
+- Optionally work with a vector database or other retrieval mechanism.
+
+Agents call Context Providers when they need **grounded, site‑specific** information instead of relying only on the base model.
+
+## Typical Data Sources
+Examples of what a Context Provider might expose:
+- MODX **Resources** (e.g., content pages, knowledge base articles)
+- MODX **Elements** (Snippets, Chunks, Templates) and their descriptions
+- Indexed documentation, FAQs, or release notes
+- External knowledge bases or search APIs
+
+## Registering Context Providers
+To add a new provider:
+- Implement a PHP class that follows the `\modAI\Tools\ToolInterface` interface.
+- Register the tool with modAI:
+    - Create a plugin that will run on `modAIOnContextProviderRegister` event and will return the class name of the Context Provider or an array of multiple context providers you wish to register.
+- Create the context provider from Context Providers tab:
+    - Select the Context Provider class
+    - A **unique name**.
+    - Set the internal description explaining what the Context Provider does
+
+Once registered, the context provider appears in the **Context Provider** tab and you’ll be able to attach it to agents.
+
+## Configuring Context Providers in the Manager
+From the **Context Providers** tab you can:
+- Enable or disable providers.
+- Attach providers to specific **Agents** so only the right agents can access a given data source.
+
+Design tips:
+- Use separate providers for very different datasets (e.g., “Public Docs”, “Internal Runbooks”, “Developer API Docs”).
+- Keep provider scopes narrow so retrieval stays relevant and efficient.
+
+## Performance and Cost
+Context providers may rely on:
+- Full‑text search queries
+- Vector database lookups
+- External API calls
+
+Be mindful of:
+- Token usage when passing large chunks of context into prompts.
+- Rate limits and pricing for external services.
+- Caching strategies to reduce repeated work.

Writerside/topics/Prompt-Library.md

@@ -1,54 +1,17 @@
 # Prompt Library
 
-Through system setting `modai.chat.prompt_library` you can define a set of prompts for both `text` and `image` chats, that the user will be able to quickly use.
+## Purpose
+The **Prompt Library** is a centralized place to store and manage reusable prompts and prompt snippets, such as:
+- Brand voice and tone guidelines
+- SEO optimization templates
+- QA or review checklists
+- Reusable task patterns (e.g., “Summarize this page for our CEO”, “Rewrite this in plain, non-technical language a 12 year old can understand”)
 
-## Example
+## Prompt Types and Visibility
+In the library you can typically designate prompts as:
+- **Public** – Available to all users who can access modAI.
+- **Private** – Only visible to the user who created them.
 
-```JSON
-{
-  "text": [
-    {
-      "name": "MODX",
-      "children": [
-        {
-          "name": "Blog",
-          "children": [
-            {
-              "name": "Step 1",
-              "value": "Say hi"
-            },
-            {
-              "name": "Step 2",
-              "value": "Say hello"
-            }
-          ]
-        },
-        {
-          "name": "Dev",
-          "children": [
-            {
-              "name": "Step 1",
-              "value": "Say I'm dev"
-            },
-            {
-              "name": "Step 2",
-              "value": "Say yo!"
-            }
-          ]
-        }
-      ]
-    }
-  ],
-  "image": [
-    {
-      "name": "Action Figure",
-      "children": [
-        {
-          "name": "Blog",
-          "value": "Create an image of an action figure like box, where the figure will be a MODX developer. Additional items in the box will be macbook, iphone and a book."
-        },
-    }
-  ]
-}
-
-```
+This is useful for:
+- Team‑wide standard prompts (public).
+- Personal workflows

Writerside/topics/Tools.md

@@ -1,28 +1,46 @@
 # Tools
 
-To be able to use tools through agents, or directly from chat, they have to be created and configured from this section.
-
-To create & configure tool, navigate to the Extras -> modAI -> Tools and hit `Create Tool` button.
-
-## Properties
-
-### Tool Class
-Implementation of the tool. Every tool class can have an additional configuration that will show up in the `Config` panel on the right side. Additional tools can be registered using plugin with `modAIOnToolRegister` event. 
-
-### Name
-Name of the tool, this name has to be unique across all configured tools. This is how AI references a tool that it wants to run.
-
-### Description
-Internal description of the tool, doesn't have any special functionality.
-
-### Prompt
-Tool's prompt (aka description in AI docs), the prompt describes how to the tools works to the AI. If empty, the default prompt (from the tool class) will be used.
-
-### Enabled
-If set to `false`, the tool won't be available for use, even when assigned to agents.
-
-### Default
-When set to `true`, the tool will be available for use in every prompt (without a need to select an agent). Be careful with enabling this on tools as it will increase token usage and can worsen the AI responses.  
-
-### Additional Config Options
-Every tool class can expose a different set of additional config options. You can reference a value from system settings by using `ss:system_setting_key` format for the config option's value.
+## What a Tool Is
+
+A **Tool** is a server‑side capability that an agent can call when it needs structured data or needs to perform an action.
+
+In modAI, Tools are generally implemented as PHP classes that:
+- Declare their **name**, **description/prompt**, and **parameters**
+- Implement logic to perform an action (e.g., read or update a MODX element, call an external API, run a search)
+- Return structured results to the agent 
+
+Think of Tools as “functions” an agent can call to go beyond plain text generation.
+
+## Common Tool Examples
+- Edit or create MODX **Templates**, **Chunks**, or **Snippets**
+- Fetch and return content from specific Resources
+- Trigger indexing jobs for a Context Provider
+- Call a third‑party API (e.g., analytics, search, CRM) and return summarized data
+
+## Registering Tools
+Tools are typically registered via configuration and/or service discovery. At a high level, you’ll:
+- Create a PHP class that implements the `\modAI\Tools\ToolInterface` interface.
+- Register the tool with modAI:
+    - Create a plugin that will run on `modAIOnToolRegister` event and will return the class name of the tool or an array of multiple Tools you wish to register.
+- Create the tool from Tools tab:
+    - Select the Tool class
+    - A **unique name** (e.g., `EditChunk`, `SearchResources`).
+    - Set the internal description explaining what the Tool does
+    - Adjust the **prompt** if needed
+
+Once registered, the tool appears in the **Tools** tab and you’ll be able to attach it to agents.
+
+## Configuring Tools in the Manager
+From the **Tools** tab you can:
+- Enable or disable individual Tools.
+- Edit the **user‑facing name** and **prompt/description**.
+- Whether a Tool is available in every prompt even without an agent
+
+Changes here do not require you to redeploy code, which makes it a safe place to iterate on prompts and defaults.
+
+## Security Considerations
+Because tools can read or modify data:
+- Ensure tools check **permissions** for the current MODX user.
+- Avoid exposing write or delete Tools to general users; instead, bind them to admin‑only Agents.
+- Validate and sanitize all input arguments.
+- Log usage for sensitive operations, especially those that change content or configuration.

assets/components/modai/mgr/css/modai.css

@@ -27,3 +27,22 @@
 .modai-admin--prompt-library_category_disabled {
     font-style: italic;
 }
+
+.modai-admin--panel_desc {
+    padding-top: 20px;
+    padding-left: 20px;
+    font-size: 14px;
+    color: #495057;
+}
+
+.modai-admin--panel_desc a {
+    color: #4a90e2;
+    text-decoration: none;
+    font-weight: 500;
+    border-bottom: 1px solid transparent;
+    transition: border-bottom-color 0.2s ease;
+}
+
+.modai-admin--panel_desc a:hover {
+    border-bottom-color: #4a90e2;
+}