Qualytics · RafaelOsiro · Jun 18, 2026 · Jun 18, 2026
diff --git a/docs/agent-q/api.md → docs/agentq/api.md b/docs/agent-q/api.md → docs/agentq/api.md
diff --git a/docs/agent-q/deep-dive/agentic.md → docs/agentq/deep-dive/agentic.md b/docs/agent-q/deep-dive/agentic.md → docs/agentq/deep-dive/agentic.md
@@ -31,7 +31,7 @@ Before using the agentic endpoints, you must configure your LLM provider credent
 
 ### Supported Providers
 
-The agentic endpoints support 22+ LLM providers. For the full list, see [Supported LLM Providers](../managing/add-integration.md#supported-llm-providers){:target="_blank"} in the Add Integration guide.
+The agentic endpoints support 22+ LLM providers. For the full list, see [Supported LLM Providers](../how-tos/add-integration.md#supported-llm-providers){:target="_blank"} in the Add Integration guide.
 
 Common providers include:
 
@@ -58,7 +58,7 @@ LLM configuration is managed through the Qualytics UI, just like any other integ
 4. Optionally provide a **Base URL** if required by your provider
 5. Click **Save** to complete the configuration
 
-For detailed setup instructions with screenshots, see [Add Integration](../managing/add-integration.md){:target="_blank"}.
+For detailed setup instructions with screenshots, see [Add Integration](../how-tos/add-integration.md){:target="_blank"}.
 
 ## Capabilities
 

diff --git a/docs/agent-q/deep-dive/best-practices.md → docs/agentq/deep-dive/best-practices.md b/docs/agent-q/deep-dive/best-practices.md → docs/agentq/deep-dive/best-practices.md
diff --git a/docs/agent-q/deep-dive/conversations.md → docs/agentq/deep-dive/conversations.md b/docs/agent-q/deep-dive/conversations.md → docs/agentq/deep-dive/conversations.md
@@ -116,13 +116,13 @@ Information from early in a long conversation is not lost. It stays available to
 
 If you navigate away from the AgentQ page while a response is being generated, the stream continues in the background. The full response is waiting for you when you return to that session.
 
-For other interface tips like stopping a response or pasting large content, see [Chat Interface Tips](../managing/chat-interface-tips.md){:target="_blank"}.
+For other interface tips like stopping a response or pasting large content, see [Chat Interface Tips](../how-tos/chat-interface-tips.md){:target="_blank"}.
 
 ### Session Persistence
 
 Every conversation is saved. When you resume a session, AgentQ restores the full message history and the conversation summary, so it picks up exactly where you left off, even across days or sessions.
 
-For step-by-step instructions on resuming a session, see [Resume a Conversation](../managing/resume-a-conversation.md){:target="_blank"}.
+For step-by-step instructions on resuming a session, see [Resume a Conversation](../how-tos/resume-a-conversation.md){:target="_blank"}.
 
 ## Example Conversations
 

diff --git a/docs/agent-q/deep-dive/in-action.md → docs/agentq/deep-dive/in-action.md b/docs/agent-q/deep-dive/in-action.md → docs/agentq/deep-dive/in-action.md
@@ -191,6 +191,6 @@ Workflow tools execute multi-step guided processes for complex tasks. Each retur
 
 ## Connecting External Clients
 
-For step-by-step instructions on connecting ChatGPT, Claude Desktop, Cursor, and other MCP-compatible clients to the Qualytics MCP server, see [Connecting External AI Clients](../managing/connecting-external-ai-clients.md){:target="_blank"}.
+For step-by-step instructions on connecting ChatGPT, Claude Desktop, Cursor, and other MCP-compatible clients to the Qualytics MCP server, see [Connecting External AI Clients](../how-tos/connecting-external-ai-clients.md){:target="_blank"}.
 
 For example conversations showing AgentQ in use, see [Conversations, Responses & Context](./conversations.md#example-conversations){:target="_blank"}.
diff --git a/docs/agent-q/deep-dive/limits.md → docs/agentq/deep-dive/limits.md b/docs/agent-q/deep-dive/limits.md → docs/agentq/deep-dive/limits.md
@@ -156,7 +156,7 @@ Very short follow-ups like *"yes"* or *"that one"* are recognized as continuatio
 
 Pastes of 1,000 characters or more into the input are captured as an attachment panel rather than inserted inline.
 
-File attachments are accepted only when the active LLM provider supports file uploads. See [Attach a File](../managing/chat-interface-tips.md#attach-a-file){:target="_blank"} for the supported formats and provider list.
+File attachments are accepted only when the active LLM provider supports file uploads. See [Attach a File](../how-tos/chat-interface-tips.md#attach-a-file){:target="_blank"} for the supported formats and provider list.
 
 ## Error Reference
 

diff --git a/docs/agent-q/deep-dive/mcp.md → docs/agentq/deep-dive/mcp.md b/docs/agent-q/deep-dive/mcp.md → docs/agentq/deep-dive/mcp.md
@@ -99,4 +99,4 @@ For data quality workflows, this means:
 ## Next Steps
 
 - [AgentQ in Action](./in-action.md){:target="_blank"} — How Qualytics implements MCP as a server.
-- [Connecting External AI Clients](../managing/connecting-external-ai-clients.md){:target="_blank"} — Connect external AI clients (ChatGPT, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Amazon Q Developer) to the Qualytics MCP server.
+- [Connecting External AI Clients](../how-tos/connecting-external-ai-clients.md){:target="_blank"} — Connect external AI clients (ChatGPT, Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Amazon Q Developer) to the Qualytics MCP server.
diff --git a/docs/agent-q/faq.md → docs/agentq/faq.md b/docs/agent-q/faq.md → docs/agentq/faq.md
@@ -30,7 +30,7 @@ No. AgentQ includes an automatic topic guardrail. Before processing a request, a
 
 ### What LLM providers are supported?
 
-AgentQ supports 22+ LLM providers including OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Groq, Mistral, DeepSeek, Cohere, Ollama, OpenRouter, Perplexity, and more. See the full list with example models in the [Add Integration](managing/add-integration.md#supported-llm-providers){:target="_blank"} guide.
+AgentQ supports 22+ LLM providers including OpenAI, Anthropic, Google Gemini, Amazon Bedrock, Groq, Mistral, DeepSeek, Cohere, Ollama, OpenRouter, Perplexity, and more. See the full list with example models in the [Add Integration](how-tos/add-integration.md#supported-llm-providers){:target="_blank"} guide.
 
 ### Do I need my own LLM API key?
 
@@ -58,7 +58,7 @@ Existing conversation history is preserved — sessions are stored independently
 
 ### What happens if I don't configure an LLM?
 
-Without an LLM configured, AgentQ displays a "No LLM Integration Configured" message with a **Configure LLM** button. The platform is fully functional otherwise — only AgentQ's chat capabilities are unavailable. Follow the [Add Integration](managing/add-integration.md){:target="_blank"} guide to get started.
+Without an LLM configured, AgentQ displays a "No LLM Integration Configured" message with a **Configure LLM** button. The platform is fully functional otherwise — only AgentQ's chat capabilities are unavailable. Follow the [Add Integration](how-tos/add-integration.md){:target="_blank"} guide to get started.
 
 ## Usage
 
@@ -108,7 +108,7 @@ Yes. Click the **Export as PDF** button below any assistant message to download
 
 ### Can I upload files to AgentQ?
 
-Yes, when your active LLM provider supports binary content. The chat input shows an **Attach** icon for PDF, Word (`.doc`, `.docx`), Excel (`.xls`, `.xlsx`), CSV, TSV, JSON, XML, plain text, and Markdown files. Limits: one file per message, up to 20 MB per file. The button is shown for Anthropic, Google Gemini, Amazon Bedrock (Claude models), OpenAI, Azure OpenAI, and Heroku. See [Attach a File](managing/chat-interface-tips.md#attach-a-file){:target="_blank"} for full details.
+Yes, when your active LLM provider supports binary content. The chat input shows an **Attach** icon for PDF, Word (`.doc`, `.docx`), Excel (`.xls`, `.xlsx`), CSV, TSV, JSON, XML, plain text, and Markdown files. Limits: one file per message, up to 20 MB per file. The button is shown for Anthropic, Google Gemini, Amazon Bedrock (Claude models), OpenAI, Azure OpenAI, and Heroku. See [Attach a File](how-tos/chat-interface-tips.md#attach-a-file){:target="_blank"} for full details.
 
 ### Are there usage limits?
 
@@ -143,7 +143,7 @@ Not directly — conversations are private to your user account. To share findin
 
 ### How long are conversations stored?
 
-Conversations persist indefinitely until you delete them. Archived conversations are also kept until explicitly deleted. See [Delete a Conversation](managing/delete-a-conversation.md){:target="_blank"} for instructions on permanent removal.
+Conversations persist indefinitely until you delete them. Archived conversations are also kept until explicitly deleted. See [Delete a Conversation](how-tos/delete-a-conversation.md){:target="_blank"} for instructions on permanent removal.
 
 ### What languages does AgentQ support?
 
@@ -157,7 +157,7 @@ The [Model Context Protocol](https://modelcontextprotocol.io/){:target="_blank"}
 
 ### Can I connect external AI clients to Qualytics?
 
-Yes. Beyond the built-in AgentQ, you can connect ChatGPT, Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, Amazon Q Developer, and any MCP-compatible client directly to the Qualytics MCP server using your Personal API Token. See the [Connecting External AI Clients](managing/connecting-external-ai-clients.md){:target="_blank"} guide for step-by-step instructions for each client.
+Yes. Beyond the built-in AgentQ, you can connect ChatGPT, Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, Amazon Q Developer, and any MCP-compatible client directly to the Qualytics MCP server using your Personal API Token. See the [Connecting External AI Clients](how-tos/connecting-external-ai-clients.md){:target="_blank"} guide for step-by-step instructions for each client.
 
 ### Which external AI clients are supported?
 
@@ -173,7 +173,7 @@ Qualytics provides step-by-step setup guides for the following MCP clients:
 | **Windsurf** | Streamable HTTP via `~/.codeium/windsurf/mcp_config.json` |
 | **Amazon Q Developer** | Streamable HTTP via `~/.aws/amazonq/mcp.json` |
 
-Any other MCP-compatible client that supports **Streamable HTTP** transport can also connect. See the [Connecting External AI Clients](managing/connecting-external-ai-clients.md){:target="_blank"} guide for full instructions.
+Any other MCP-compatible client that supports **Streamable HTTP** transport can also connect. See the [Connecting External AI Clients](how-tos/connecting-external-ai-clients.md){:target="_blank"} guide for full instructions.
 
 ### Do external clients have the same capabilities as AgentQ?
 

diff --git a/docs/agent-q/managing/add-integration.md → docs/agentq/how-tos/add-integration.md b/docs/agent-q/managing/add-integration.md → docs/agentq/how-tos/add-integration.md
@@ -6,7 +6,7 @@ AgentQ requires an LLM (Large Language Model) provider to power its AI capabilit
 
 The setup below opens the **LLM Configuration** modal. Use this reference to understand what each field expects before going through the steps:
 
-![llm-modal-fields](../../assets/agent-q/managing/add-integration/llm-modal-fields.png)
+![llm-modal-fields](../../assets/agentq/how-tos/add-integration/llm-modal-fields.png)
 
 | # | Field | Description |
 |---|-------|-------------|
@@ -29,56 +29,56 @@ The LLM Configuration modal can be opened from two places. Both paths lead to th
 
     **Step 1:** Click the **Settings** :material-cog: icon in the bottom-left sidebar.
 
-    ![settings-icon](../../assets/agent-q/managing/shared/settings-icon.png)
+    ![settings-icon](../../assets/agentq/how-tos/shared/settings-icon.png)
 
     **Step 2:** The Settings page opens on the **Connections** tab.
 
-    ![settings-connections](../../assets/agent-q/managing/shared/settings-connections.png)
+    ![settings-connections](../../assets/agentq/how-tos/shared/settings-connections.png)
 
     **Step 3:** Click the **Integrations** tab.
 
-    ![step-3-settings-integrations](../../assets/agent-q/managing/add-integration/step-3-settings-integrations.png)
+    ![step-3-settings-integrations](../../assets/agentq/how-tos/add-integration/step-3-settings-integrations.png)
 
 === "From AgentQ"
 
     **Step 1:** Click **AgentQ** :material-robot: in the left sidebar to open the AgentQ page.
 
-    ![step-1-agent-q-icon](../../assets/agent-q/managing/add-integration/step-1-agent-q-icon.png)
+    ![step-1-agentq-icon](../../assets/agentq/how-tos/add-integration/step-1-agentq-icon.png)
 
     **Step 2:** The **No LLM Integration Configured** page appears.
 
-    ![step-2-agent-q-no-llm](../../assets/agent-q/managing/add-integration/step-2-agent-q-no-llm.png)
+    ![step-2-agentq-no-llm](../../assets/agentq/how-tos/add-integration/step-2-agentq-no-llm.png)
 
     **Step 3:** Click **Configure LLM**. You are redirected to **Settings** > **Integrations**.
 
-    ![step-3-agent-q-configure](../../assets/agent-q/managing/add-integration/step-3-agent-q-configure.png)
+    ![step-3-agentq-configure](../../assets/agentq/how-tos/add-integration/step-3-agentq-configure.png)
 
 ## Configure the LLM Provider
 
 Once you are on the **Integrations** tab, continue from this step regardless of which path you took above.
 
 **Step 4:** The **Integrations** page lists every integration available in Qualytics, grouped by category. The **AgentQ** section is at the top with the **LLM Configuration** entry.
 
-![step-4-integrations-page](../../assets/agent-q/managing/add-integration/step-4-integrations-page.png)
+![step-4-integrations-page](../../assets/agentq/how-tos/add-integration/step-4-integrations-page.png)
 
 **Step 5:** Click **Connect** next to **LLM Configuration**.
 
-![step-5-connect](../../assets/agent-q/managing/add-integration/step-5-connect.png)
+![step-5-connect](../../assets/agentq/how-tos/add-integration/step-5-connect.png)
 
 **Step 6:** The **LLM Configuration** modal opens. Fill in the fields described in [LLM Configuration Fields](#llm-configuration-fields) above.
 
-![step-6-modal](../../assets/agent-q/managing/add-integration/step-6-modal.png)
+![step-6-modal](../../assets/agentq/how-tos/add-integration/step-6-modal.png)
 
 **Step 7:** Click **Save** to complete the configuration.
 
-![step-7-save](../../assets/agent-q/managing/add-integration/step-7-save.png)
+![step-7-save](../../assets/agentq/how-tos/add-integration/step-7-save.png)
 
 !!! info
     When you save, Qualytics automatically validates your API key and tests the connection to the provider. If the key is invalid or the provider is unreachable, you will see an error before the configuration is stored. Qualytics also checks whether your provider supports web search — if it does, AgentQ can optionally search the Qualytics documentation to answer platform-related questions.
 
 **Step 8:** A confirmation message appears and the **LLM Configuration** entry now shows a **Connected** badge with the active provider and model.
 
-![step-8-connected](../../assets/agent-q/managing/add-integration/step-8-connected.png)
+![step-8-connected](../../assets/agentq/how-tos/add-integration/step-8-connected.png)
 
 Once saved, AgentQ is ready to use. See [AgentQ Overview](../overview.md){:target="_blank"} for next steps.
 

diff --git a/...gent-q/managing/archive-a-conversation.md → .../agentq/how-tos/archive-a-conversation.md b/...gent-q/managing/archive-a-conversation.md → .../agentq/how-tos/archive-a-conversation.md
@@ -9,19 +9,19 @@ Archiving moves a conversation out of the active **Chats** list into the **Archi
 
 **Step 1:** In the sidebar, hover over the conversation you want to archive and click the **More options** :material-dots-vertical: menu icon that appears next to it.
 
-![kebab-menu](../../assets/agent-q/managing/shared/kebab-menu.png)
+![kebab-menu](../../assets/agentq/how-tos/shared/kebab-menu.png)
 
 **Step 2:** A dropdown opens with the available conversation actions.
 
-![menu-options](../../assets/agent-q/managing/shared/menu-options.png)
+![menu-options](../../assets/agentq/how-tos/shared/menu-options.png)
 
 **Step 3:** Select **Archive** :material-archive-outline:.
 
-![archive-menu](../../assets/agent-q/managing/archive-a-conversation/archive-menu.png)
+![archive-menu](../../assets/agentq/how-tos/archive-a-conversation/archive-menu.png)
 
 **Step 4:** A success message appears and the conversation moves to the **Archived** section at the bottom of the sidebar.
 
-![chat-archived](../../assets/agent-q/managing/archive-a-conversation/chat-archived.png)
+![chat-archived](../../assets/agentq/how-tos/archive-a-conversation/chat-archived.png)
 
 !!! info
     If you archive the conversation you are currently viewing, you are automatically redirected to the AgentQ empty state.

diff --git a/docs/agent-q/managing/chat-interface-tips.md → docs/agentq/how-tos/chat-interface-tips.md b/docs/agent-q/managing/chat-interface-tips.md → docs/agentq/how-tos/chat-interface-tips.md
@@ -6,7 +6,7 @@ Quick reference for the controls available in the AgentQ interface.
 
 The full-page chat opens when you click **AgentQ** in the left sidebar. It has a collapsible **Chats** sidebar on the left and the main chat area on the right.
 
-![full-page-overview](../../assets/agent-q/managing/chat-interface-tips/full-page-overview.png)
+![full-page-overview](../../assets/agentq/how-tos/chat-interface-tips/full-page-overview.png)
 
 | # | Button | Icon | Description |
 |---|---|---|---|
@@ -23,7 +23,7 @@ The full-page chat opens when you click **AgentQ** in the left sidebar. It has a
 
 The floating chat is the persistent widget in the bottom-right corner of every page. Click the **AgentQ** button to open it; press ++q++ to toggle it from anywhere on the page (except while typing in an input).
 
-![floating-overview](../../assets/agent-q/managing/chat-interface-tips/floating-overview.png)
+![floating-overview](../../assets/agentq/how-tos/chat-interface-tips/floating-overview.png)
 
 | # | Button | Icon | Description |
 |---|---|---|---|
@@ -38,31 +38,31 @@ The floating chat is the persistent widget in the bottom-right corner of every p
 
 While AgentQ is generating, the **Send** button becomes a **Stop** :material-stop: button. Click it to interrupt the response — whatever AgentQ produced so far is preserved as a partial response with a "Stopped" indicator.
 
-![stop](../../assets/agent-q/managing/chat-interface-tips/stop.png)
+![stop](../../assets/agentq/how-tos/chat-interface-tips/stop.png)
 
 The same control is available in the floating chat:
 
-![stop-floating](../../assets/agent-q/managing/chat-interface-tips/stop-floating.png)
+![stop-floating](../../assets/agentq/how-tos/chat-interface-tips/stop-floating.png)
 
 ## Paste Large Content
 
 When you paste text of 1,000 characters or more into the input, AgentQ captures it as an attachment rather than inserting it into the input field. The pasted content appears as a removable panel labeled **PASTED** above the input. It is included with your message when you send it, giving AgentQ full context while keeping the input clean.
 
-![large-content](../../assets/agent-q/managing/chat-interface-tips/large-content.png)
+![large-content](../../assets/agentq/how-tos/chat-interface-tips/large-content.png)
 
 In the floating chat, the pasted content appears as a compact chip:
 
-![pasted-floating](../../assets/agent-q/managing/chat-interface-tips/pasted-floating.png)
+![pasted-floating](../../assets/agentq/how-tos/chat-interface-tips/pasted-floating.png)
 
 ## Attach a File
 
 When your active LLM provider supports file uploads, click the **Attach** :material-paperclip: icon next to the message input, choose a document in the native file picker, and click **Open**. The selected file appears as a removable chip above the input — type your prompt and send the message, and the file is sent together with your text.
 
-![attached-file](../../assets/agent-q/managing/chat-interface-tips/attached-file.png)
+![attached-file](../../assets/agentq/how-tos/chat-interface-tips/attached-file.png)
 
 In the floating chat, the attached file appears as a compact chip:
 
-![attached-file-floating](../../assets/agent-q/managing/chat-interface-tips/attached-file-floating.png)
+![attached-file-floating](../../assets/agentq/how-tos/chat-interface-tips/attached-file-floating.png)
 
 **Supported file types**