docs: fix decopilot tool names, concepts entities, monitoring scope, API keys

- Fix decopilot tool names: tool_search/tool_enable removed (not real tools),
  subtask_run → subtask, resource_read → read_resource, prompt_read → read_prompt
- Add missing tools: sandbox, read_tool_output, propose_plan
- Add subtask restrictions: 15 step limit, must return summary
- Fix task status: "Success" → "completed" with actual enum values
- Update concepts: agents/projects share subtype field, add Thread, Event Bus, Tags, AI Provider Keys
- Clarify monitoring scope: only MCP proxy calls logged, not management API
- Fix API keys: remove Settings UI references, document permission format
- All fixes applied to both EN and PT-BR

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cecilia-marques

apps/docs/client/src/content/deco-studio/en/studio/api-keys.mdx

@@ -28,15 +28,14 @@ API keys let external systems connect to deco Studio without needing a user to l
 
 ## Creating an API Key
 
-1. Open the **deco Studio Dashboard**
-2. Go to **Settings** → **API Keys**
-3. Click **Create API Key**
-4. Give it a name (like "My Automation Script")
-5. Assign [roles and permissions](/en/studio/user-management)
-6. **Copy the key immediately**
+API keys are managed through the management MCP tools or the API. When creating an API key, you specify:
+
+1. A descriptive name (like "My Automation Script")
+2. Direct permissions in the format `{ resource: [actions...] }` — where the resource is either `"self"` for management tools or `"conn_<UUID>"` for connection-specific access
+3. **Copy the key immediately** — it is only shown once
 
 <Callout type="error">
-  You can only see the API key once. Copy it now and store it somewhere safe like a password manager.
+  You can only see the API key once. Store it somewhere safe like a password manager.
 </Callout>
 
 ## Using Your API Key

apps/docs/client/src/content/deco-studio/en/studio/concepts.mdx

@@ -9,14 +9,18 @@ icon: BookOpen
 - **Organization**: the top-level tenant boundary. Everything (connections, agents, projects, logs) is org-scoped.
 - **Members**: users invited into an organization with specific roles and permissions.
 - **Connection**: a configured upstream MCP endpoint (usually HTTP), optionally with stored credentials. See [Connections](/en/studio/connections).
-- **Virtual MCP**: aggregates tools/resources/prompts from connected servers into a single MCP. See [Virtual MCPs](/en/studio/virtual-mcps).
-- **Agent**: single-purpose Virtual MCPs optimized for specific tasks. See [Agents](/en/studio/agents).
+- **Virtual MCP**: aggregates tools/resources/prompts from connected servers into a single MCP. Agents and Projects are both Virtual MCPs distinguished by a `subtype` field. See [Virtual MCPs](/en/studio/virtual-mcps).
+- **Agent**: a Virtual MCP with subtype `agent` — focused on specific tasks with a curated toolset. See [Agents](/en/studio/agents).
+- **Project**: a Virtual MCP with subtype `project` — organizes project-specific tools, resources, prompts, and config. See [Projects](/en/studio/projects).
 - **Automation**: unattended agent runs on a schedule or event trigger. See [Automations](/en/studio/automations).
-- **Project**: Virtual MCPs to organize project-specific tools, resources, prompts, and config. See [Projects](/en/studio/projects).
+- **Thread**: a persistent conversation session with an agent. Stores chat messages and tracks status (`in_progress`, `requires_action`, `completed`, `failed`).
+- **Event Bus**: pub/sub system between connections following CloudEvents v1.0 spec. Supports scheduled delivery, cron-based recurring events, and at-least-once delivery guarantees.
+- **Tags**: organization-level labels for categorizing and filtering members.
+- **AI Provider Keys**: API key management for AI model providers (e.g. OpenRouter).
 
 ## Understanding Agents vs. Projects
 
-Both agents and projects are Virtual MCPs, but they serve different purposes in your workflow:
+Both agents and projects are Virtual MCPs stored in the same `connections` table, distinguished by a `subtype` field (`agent` or `project`). They serve different purposes in your workflow:
 
 **Projects** are general-purpose organizational units for ongoing work:
 - **Broad scope** - Cover multiple workflows and capabilities within a work context
@@ -32,7 +36,7 @@ Both agents and projects are Virtual MCPs, but they serve different purposes in
 - **Example** - "Refund Processing Agent" that only handles customer refunds and return authorizations
 - **When to use** - Focused operations, built-in mesh management, or specialized workflows
 
-Both follow the same Virtual MCP architecture, but their design principles differ: projects organize capabilities for broad work contexts, while agents are reusable configurations that can be instantiated on-demand with fresh execution state.
+Both share the same Virtual MCP architecture and storage model, but their design principles differ: projects organize capabilities for broad work contexts, while agents are reusable configurations that can be instantiated on-demand with fresh execution state.
 
 ## MCP Protocol Primitives
 

apps/docs/client/src/content/deco-studio/en/studio/decopilot/context.mdx

@@ -116,7 +116,7 @@ See [Agents](/en/studio/agents) for more on how agents provide fresh, focused co
 
 ## How Scopes Affect Context
 
-Each [scope](/en/studio/decopilot/scopes) has access only to its own tools and resources. When you switch scopes, the tools available through `tool_search` change to match that scope's virtual MCP, and the instructions that load into the scope instructions slot change—organization, project, or agent-specific. See [Scopes](/en/studio/decopilot/scopes) for details.
+Each [scope](/en/studio/decopilot/scopes) has access only to its own tools and resources. When you switch scopes, the tools available through the scope's tools change to match that scope's virtual MCP, and the instructions that load into the scope instructions slot change—organization, project, or agent-specific. See [Scopes](/en/studio/decopilot/scopes) for details.
 
 ## Practical Tips
 

apps/docs/client/src/content/deco-studio/en/studio/decopilot/tasks-and-spawning.mdx

@@ -31,10 +31,10 @@ Tasks move through different states as work progresses. Understanding these stat
 
 Every task has one of four statuses:
 
-- **In Progress** - Active work happening, agent is executing or waiting for next message
-- **Requires Action** - Paused, waiting for your input (tool approval or question response)
-- **Success** - Work completed successfully
-- **Failed** - Something went wrong or task timed out
+- **In Progress** (`in_progress`) - Active work happening, agent is executing or waiting for next message
+- **Requires Action** (`requires_action`) - Paused, waiting for your input (tool approval or question response)
+- **Completed** (`completed`) - Work completed successfully
+- **Failed** (`failed`) - Something went wrong or task timed out
 
 ### When Tasks Require Attention
 
@@ -77,7 +77,7 @@ This makes subtasks perfect for intensive work that would otherwise fill up your
 When you spawn a subtask:
 
 1. **Fresh start** - Subtask begins with clean context (just scope instructions and system prompt)
-2. **Independent execution** - Subtask is a regular task with restricted built-in tools (no `subtask_run` or `user_ask`)
+2. **Independent execution** - Subtask is a regular task with restricted built-in tools (no `subtask` or `user_ask`)
 3. **Summary return** - Parent task receives only a concise summary (200-500 tokens)
 4. **Full details preserved** - Complete subtask conversation saved in task history
 
@@ -88,7 +88,7 @@ The parent task sees just the summary—keeping your main conversation lean—wh
 | Feature | Main Task | Subtask |
 |---------|-----------|---------|
 | Context | Accumulated history | Fresh, clean start |
-| Available tools | All built-in tools + current scope's tools | Same, but no `subtask_run` or `user_ask` |
+| Available tools | All built-in tools + current scope's tools | Same, but no `subtask` or `user_ask` |
 | Result visibility | Full conversation | Summary only to parent |
 | User interaction | Can ask questions (`user_ask`) | Cannot ask questions |
 

apps/docs/client/src/content/deco-studio/en/studio/decopilot/tools.mdx

@@ -12,7 +12,7 @@ import Callout from "../../../../../components/ui/Callout.astro";
 
 ## Overview
 
-Decopilot uses two types of tools: **built-in tools** for discovering capabilities and managing work, and **scope tools** from the current [scope](/en/studio/decopilot/scopes) for domain-specific actions. Tools are discovered with `tool_search` and activated on-demand with `tool_enable`, keeping execution focused and preventing tool overload.
+Decopilot uses two types of tools: **built-in tools** for discovering capabilities and managing work, and **scope tools** from the current [scope](/en/studio/decopilot/scopes) for domain-specific actions. Scope tools are available based on the connections in the current scope's Virtual MCP — decopilot sees them listed in its system prompt.
 
 ## Tool Reference
 
@@ -23,19 +23,20 @@ All built-in tools are available across all scopes. Availability varies between
 | Tool | Task | Subtask | Description |
 |------|:----:|:-------:|-------------|
 | **Discovery** |
-| `tool_search` | ✓ | ✓ | Search for tools in current scope |
-| `tool_enable` | ✓ | ✓ | Activate a tool for use in current task |
 | `agent_search` | ✓ | ✓ | Find agents configured in the organization |
 | **Execution** |
-| `subtask_run` | ✓ | ✗ | Spawn subtask with fresh context, optionally specifying an agent |
+| `subtask` | ✓ | ✗ | Spawn subtask with fresh context, optionally specifying an agent |
 | `user_ask` | ✓ | ✗ | Ask user for input or clarification |
+| `sandbox` | ✓ | ✓ | Execute JavaScript code with access to MCP tools |
 | **Context** |
-| `resource_read` | ✓ | ✓ | Read documentation/guidelines from current scope (supports line ranges) |
-| `prompt_read` | ✓ | ✓ | Read prompt templates from current scope |
+| `read_resource` | ✓ | ✓ | Read documentation/guidelines from current scope (supports line ranges) |
+| `read_prompt` | ✓ | ✓ | Read prompt templates from current scope |
+| `read_tool_output` | ✓ | ✓ | Filter large tool outputs using regex patterns |
+| `propose_plan` | ✓ | ✗ | Propose execution plans for user approval (in "plan" approval mode) |
 
 ### Scope Tools
 
-Scope tools come from the current scope—domain-specific capabilities like Shopify, inventory systems, or shipping tools. These are discovered via `tool_search` and enabled via `tool_enable`.
+Scope tools come from the current scope—domain-specific capabilities like Shopify, inventory systems, or shipping tools. These are available based on the connections configured in the scope's Virtual MCP.
 
 **Example**: A project with Shopify and ShipStation connections might expose:
 - `GET_ORDERS` - Fetch customer orders
@@ -65,44 +66,44 @@ These annotations allow decopilot to respect tool constraints automatically. For
 **Subtasks** are spawned by decopilot for parallel work, specialized execution, or isolated context. They have restricted access:
 - **Cannot spawn additional subtasks** - Prevents infinite delegation
 - **Cannot ask user questions** - Subtasks run autonomously without blocking
+- **Step limit of 15** (vs parent's 30) - Ensures subtasks stay focused
+- **Must return a summary** - Results flow back to the parent task
 
 These restrictions ensure subtasks complete independently and don't create blocking dependencies.
 
 ## Tool Discovery Flow
 
 Decopilot starts each task with only built-in tools, then discovers and enables capabilities as needed:
 
-1. **Explore** - Use `tool_search` to see what's available in the current scope
-2. **Enable** - Use `tool_enable` to activate specific tools for the task
-3. **Execute** - Use enabled tools to accomplish work
-4. **Delegate** - Spawn subtasks via `subtask_run` for parallel or specialized work
-
-This discover-and-enable pattern ensures decopilot deliberately chooses its toolset rather than being overwhelmed by every available capability.
+1. **Explore** - Scope tools are listed in the system prompt based on the current Virtual MCP
+2. **Execute** - Use available tools to accomplish work
+3. **Delegate** - Spawn subtasks via `subtask` for parallel or specialized work
+4. **Read context** - Use `read_resource` and `read_prompt` to load domain knowledge
 
 ## Common Workflows
 
-### Discover-Enable-Execute
+### Execute Scope Tools
 
 The most common pattern for using scope tools:
 
-1. Search for capabilities with `tool_search`
-2. Enable specific tools with `tool_enable`
-3. Use enabled tools to accomplish work
+1. Review available tools from the current scope
+2. Use tools to accomplish the requested work
+3. Read resources/prompts for domain context when needed
 
 ### Delegate to Specialists
 
 For work requiring specialized expertise:
 
 1. Search for agents with `agent_search`
-2. Spawn a subtask with `subtask_run` and specific agent
+2. Spawn a subtask with `subtask` and specific agent
 3. Continue main task while subtask runs in parallel
 
 ### Context-Driven Execution
 
 For tasks requiring domain knowledge:
 
-1. Read relevant resources with `resource_read`
-2. Read workflow templates with `prompt_read`
+1. Read relevant resources with `read_resource`
+2. Read workflow templates with `read_prompt`
 3. Use context to inform tool selection and execution
 
 ---

apps/docs/client/src/content/deco-studio/en/studio/monitoring.mdx

@@ -11,7 +11,7 @@ import Callout from "../../../../components/ui/Callout.astro";
 deco Studio treats monitoring as **infrastructure, not an afterthought**. Every tool invocation that flows through the control plane creates a monitoring log—there's no way to disable this, and that's by design.
 
 <Callout type="tip">
-**Every tool call is monitored by deco Studio.** Whether it's a simple GitHub query or a complex database operation, every MCP tool invocation creates a structured log entry with full request/response details, timing, attribution, and error information. This happens automatically—no configuration required.
+**MCP proxy tool calls are monitored by deco Studio.** Tool invocations that flow through connections and Virtual MCPs (e.g., GitHub queries, database operations, Shopify calls) create structured log entries with full request/response details, timing, attribution, and error information. This happens automatically—no configuration required. Internal management API operations (creating connections, managing API keys) are not included in monitoring logs.
 </Callout>
 
 Traditional MCP deployments have fragmented observability: each client logs independently (or doesn't log at all), each MCP server has its own logging strategy, and there's no unified view of what happened across the system. deco Studio solves this by logging **at the control plane level**, creating a single source of truth for all MCP traffic.

apps/docs/client/src/content/deco-studio/pt-br/studio/api-keys.mdx

@@ -28,15 +28,14 @@ API keys permitem que sistemas externos se conectem ao deco Studio sem precisar
 
 ## Criando uma API Key
 
-1. Abra o **Painel do deco Studio**
-2. Vá em **Settings** → **API Keys**
-3. Clique em **Create API Key**
-4. Dê um nome (como "Meu Script de Automação")
-5. Atribua [papéis e permissões](/pt-br/studio/user-management)
-6. **Copie a chave imediatamente**
+API keys são gerenciadas através das ferramentas MCP de gerenciamento ou da API. Ao criar uma API key, você especifica:
+
+1. Um nome descritivo (como "Meu Script de Automação")
+2. Permissões diretas no formato `{ resource: [actions...] }` — onde o recurso é `"self"` para ferramentas de gerenciamento ou `"conn_<UUID>"` para acesso específico a conexões
+3. **Copie a chave imediatamente** — ela só é exibida uma vez
 
 <Callout type="error">
-  Você só pode ver a API key uma vez. Copie agora e armazene em um lugar seguro como um gerenciador de senhas.
+  Você só pode ver a API key uma vez. Armazene em um lugar seguro como um gerenciador de senhas.
 </Callout>
 
 ## Usando Sua API Key

apps/docs/client/src/content/deco-studio/pt-br/studio/concepts.mdx

@@ -9,14 +9,18 @@ icon: BookOpen
 - **Organização**: o limite de tenant de nível superior. Tudo (conexões, agentes, projetos, logs) é escopado por organização.
 - **Membros**: usuários convidados para uma organização com papéis e permissões específicos.
 - **Conexão**: um endpoint MCP upstream configurado (geralmente HTTP), opcionalmente com credenciais armazenadas. Veja [Conexões](/pt-br/studio/connections).
-- **MCP Virtual**: agrega ferramentas/recursos/prompts de servidores conectados em um único MCP. Veja [MCPs Virtuais](/pt-br/studio/virtual-mcps).
-- **Agente**: MCPs Virtuais de propósito único otimizados para tarefas específicas. Veja [Agentes](/pt-br/studio/agents).
+- **MCP Virtual**: agrega ferramentas/recursos/prompts de servidores conectados em um único MCP. Agentes e Projetos são ambos MCPs Virtuais diferenciados por um campo `subtype`. Veja [MCPs Virtuais](/pt-br/studio/virtual-mcps).
+- **Agente**: um MCP Virtual com subtype `agent` — focado em tarefas específicas com conjunto curado de ferramentas. Veja [Agentes](/pt-br/studio/agents).
+- **Projeto**: um MCP Virtual com subtype `project` — organiza ferramentas, recursos, prompts e configurações específicas de projeto. Veja [Projetos](/pt-br/studio/projects).
 - **Automação**: execuções autônomas de agentes em agendamento ou gatilho de evento. Veja [Automações](/pt-br/studio/automations).
-- **Projeto**: MCPs Virtuais para organizar ferramentas, recursos, prompts e configurações específicas de projeto. Veja [Projetos](/pt-br/studio/projects).
+- **Thread**: uma sessão de conversa persistente com um agente. Armazena mensagens de chat e rastreia status (`in_progress`, `requires_action`, `completed`, `failed`).
+- **Event Bus**: sistema pub/sub entre conexões seguindo a spec CloudEvents v1.0. Suporta entrega agendada, eventos recorrentes via cron e garantias de entrega at-least-once.
+- **Tags**: labels no nível da organização para categorizar e filtrar membros.
+- **Chaves de Provedor de IA**: gerenciamento de API keys para provedores de modelos de IA (ex: OpenRouter).
 
 ## Entendendo Agentes vs. Projetos
 
-Tanto agentes quanto projetos são MCPs Virtuais, mas servem propósitos diferentes no seu fluxo de trabalho:
+Tanto agentes quanto projetos são MCPs Virtuais armazenados na mesma tabela `connections`, diferenciados por um campo `subtype` (`agent` ou `project`). Eles servem propósitos diferentes no seu fluxo de trabalho:
 
 **Projetos** são unidades organizacionais de uso geral para trabalho contínuo:
 - **Escopo amplo** - Cobrem múltiplos fluxos de trabalho e capacidades dentro de um contexto de trabalho
@@ -32,7 +36,7 @@ Tanto agentes quanto projetos são MCPs Virtuais, mas servem propósitos diferen
 - **Exemplo** - "Agente de Processamento de Reembolsos" que apenas processa reembolsos e autorizações de devolução de clientes
 - **Quando usar** - Operações focadas, gerenciamento integrado do mesh ou fluxos de trabalho especializados
 
-Ambos seguem a mesma arquitetura de MCP Virtual, mas seus princípios de design diferem: projetos organizam capacidades para contextos de trabalho amplos, enquanto agentes são configurações reutilizáveis que podem ser instanciadas sob demanda com estado de execução limpo.
+Ambos compartilham a mesma arquitetura e modelo de armazenamento de MCP Virtual, mas seus princípios de design diferem: projetos organizam capacidades para contextos de trabalho amplos, enquanto agentes são configurações reutilizáveis que podem ser instanciadas sob demanda com estado de execução limpo.
 
 ## Primitivas do Protocolo MCP
 

apps/docs/client/src/content/deco-studio/pt-br/studio/decopilot/context.mdx

@@ -116,7 +116,7 @@ Veja [Agentes](/pt-br/studio/agents) para mais sobre como agentes fornecem conte
 
 ## Como os Escopos Afetam o Contexto
 
-Cada [escopo](/pt-br/studio/decopilot/scopes) tem acesso apenas as suas proprias ferramentas e recursos. Quando voce troca de escopo, as ferramentas disponiveis atraves do `tool_search` mudam para corresponder ao MCP virtual daquele escopo, e as instrucoes que carregam no slot de instrucoes de escopo mudam — organizacao, projeto ou agente especifico. Veja [Escopos](/pt-br/studio/decopilot/scopes) para detalhes.
+Cada [escopo](/pt-br/studio/decopilot/scopes) tem acesso apenas as suas proprias ferramentas e recursos. Quando voce troca de escopo, as ferramentas disponiveis do escopo mudam para corresponder ao MCP virtual daquele escopo, e as instrucoes que carregam no slot de instrucoes de escopo mudam — organizacao, projeto ou agente especifico. Veja [Escopos](/pt-br/studio/decopilot/scopes) para detalhes.
 
 ## Dicas Praticas