From 42ab000c7b62477f8514a369b657e6177d7319cd Mon Sep 17 00:00:00 2001
From: "cristiano.hoshikawa" <cristiano.hoshikawa@oracle.com>
Date: Thu, 27 Aug 2026 10:28:23 -0300
Subject: [PATCH] Documentation organization

---
 .idea/workspace.xml                           |  117 +-
 .../en/01_architecture_and_concepts.md        |  206 +-
 .../02_routing_stickiness_and_intent_shift.md | 2120 +++++++----
 .../en/03_transaction_workflows_and_state.md  | 1035 ++----
 .../04_mcp_integration_tools_and_policies.md  | 1504 ++++----
 .../05_agent_gateway_mcp_gateway_and_auth.md  | 3169 ++++++++++++-----
 ...rails_judges_and_transaction_evaluation.md |  724 +---
 .../07_rag_business_context_and_grounding.md  |  830 ++---
 .../en/08_long_term_memory_and_checkpoint.md  |  919 +----
 .../en/09_llm_rich_response_reasoning.md      |  555 +--
 .../10_performance_cache_and_async_runtime.md |  791 ++--
 ...y_persistence_and_operational_readiness.md | 1435 ++++----
 docs/developer/en/INDEX_DEVELOPER_GUIDE.md    |  148 +-
 .../en/VALIDATION_README_ALIGNMENT.md         |   48 +-
 .../02_routing_stickiness_and_intent_shift.md |    7 +
 15 files changed, 6548 insertions(+), 7060 deletions(-)

diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 43a249e..64d1784 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -6,120 +6,7 @@
   <component name="ChangeListManager">
     <list default="true" id="30a0e1d8-9d7d-469b-b241-f300911cee8a" name="Changes" comment="Ajustes na documentação e remanejamento dos folders">
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/.oca/custom_code_review_guidelines.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Arquitetura_Geral_Agent_Framework_OCI.docx" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/FIX_DEADLOCK_SEQUENCE_CROSS_LOOP.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/IMPLEMENTACAO_WORKFLOWS_TRANSACIONAIS.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/INVENTARIO_AGENT_GATEWAY_MCP_GATEWAY.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Implementando_Basic_Auth.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Long_Term_Memory_Implementation_Guide_EN.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/MANUAL_AGENT_PLATFORM_GATEWAYS.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/MANUAL_EXECUCAO_AGENT_GATEWAY_MCP_GATEWAY_FRONTEND.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/MCP_GATEWAY_RUNBOOK.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Manual de Roteamento Multi-Agent.docx" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Manual_Desenvolvedor_AI_Agent_Framework_OCI.docx" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Manual_Integracao_MCP_Servers_Agent_Framework.docx" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Manual_Long_Term_Memory_PT.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_CHECKPOINT_ENTERPRISE.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_ENTERPRISE_ROUTING.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_FIRST_ENTERPRISE_DELTA.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_FIRST_ENTERPRISE_PLUS.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_FIRST_MAX_OPERATIONAL_FIXES.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_FIRST_READY.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_GUARDRAILS_IMPLEMENTADOS.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_MAX_OPERACIONAL.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_MCP.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_MULTI_AGENT_ISOLATION.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_ROUTE_STICKINESS_SEMANTICA.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_ROUTING_MODES.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_SEMANTIC_ROUTE_STICKINESS.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_TEMPLATE_BUSINESS_CONTEXT_V2.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_TESTES_UNITARIOS.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_TOOL_POLICIES.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_old.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/README_old2.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/RELEASE_NOTES_GENERIC_DETERMINISTIC_INTENT_SHIFT_V15.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/RELEASE_NOTES_MCP_PARAMETER_EXTRACTION_FIX.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/RELEASE_NOTES_ROUTE_STICKINESS_DETERMINISTIC_INTENT_SHIFT_V14.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/RELEASE_NOTES_ROUTE_STICKINESS_TRANSACTION_SHIFT.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/RELEASE_NOTES_TOOL_POLICIES.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Release Notes/DIFF_AGENT_FRAMEWORK_LOCAL_VS_OCI_2026-08-12.pdf" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/Route_Stickiness_Semantica_Agent_Framework_OCI.docx" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/TEST_RESULTS_ROUTE_STICKINESS.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/VALIDACAO_TRANSACIONAL_BACKEND_MCP.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/docs_GLOBAL_SUPERVISOR_VALIDATION.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/docs_VALIDATION_GUARDRAILS_IC.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/Documentacao/img.png" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/README_en.md" beforeDir="false" afterPath="$PROJECT_DIR$/README_en.md" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/01_billing_agent_invoice_policy.pdf" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/02_orders_agent_lifecycle_policy.pdf" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/03_product_agent_catalog_policy.pdf" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/04_support_agent_sla_policy.pdf" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/05_business_context_rag_flow.pdf" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/ADR_TRANSACTIONAL_WORKFLOW_ENGINE.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/EXTERNAL_GUARDRAILS_JUDGES.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/JUDGES_TRANSACTIONAL_SAMPLING_FIX.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/LLM_RICH_RESPONSE.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/MCP_GATEWAY_DISCOVERY.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/MODULAR_REMAP.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/PERFORMANCE_OPTIMIZATIONS_MCP_JUDGES_RAG.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/RAG_PROVIDER_KBDB.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/README_rag_samples.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/TRANSACTION_OPERATIONAL_EVIDENCE_FIX.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/TRANSACTION_STATE_DEVELOPER_GUIDE_en.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/docs_GLOBAL_SUPERVISOR_VALIDATION.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/docs_VALIDATION_GUARDRAILS_IC.txt" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/01_authentication.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/02_deterministic_transactional_workflow.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/03_domain_requested_llm_composition.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/04_domain_requested_rag.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/05_long_term_memory.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/06_offline_workflow_regression.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/07_pause_resume_workflow.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/08_route_stickiness.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/09_voice_interruption_replay.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/10_workflow_error_recovery.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/11_clarification.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/12_durable_idempotency.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/13_dynamic_transaction_states.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/14_post_finalization_replay.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/15_retrieval_tool_guardrails.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/README.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/01_authentication.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/02_deterministic_transactional_workflow.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/03_domain_requested_llm_composition.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/04_domain_requested_rag.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/05_long_term_memory.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/06_offline_workflow_regression.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/07_pause_resume_workflow.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/08_route_stickiness.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/09_voice_interruption_replay.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/10_workflow_error_recovery.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/11_clarification.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/12_durable_idempotency.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/13_dynamic_transaction_states.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/14_post_finalization_replay.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/15_retrieval_tool_guardrails.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/en/README.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/01_authentication.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/02_deterministic_transactional_workflow.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/03_domain_requested_llm_composition.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/04_domain_requested_rag.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/05_long_term_memory.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/06_offline_workflow_regression.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/07_pause_resume_workflow.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/08_route_stickiness.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/09_voice_interruption_replay.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/10_workflow_error_recovery.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/11_clarification.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/12_durable_idempotency.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/13_dynamic_transaction_states.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/14_post_finalization_replay.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/15_retrieval_tool_guardrails.md" beforeDir="false" />
-      <change beforePath="$PROJECT_DIR$/docs/features/pt-BR/README.md" beforeDir="false" />
+      <change beforePath="$PROJECT_DIR$/docs/developer/pt/02_routing_stickiness_and_intent_shift.md" beforeDir="false" afterPath="$PROJECT_DIR$/docs/developer/pt/02_routing_stickiness_and_intent_shift.md" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -209,7 +96,7 @@
       <workItem from="1785414225783" duration="148000" />
       <workItem from="1785414447653" duration="704000" />
       <workItem from="1785630146329" duration="316000" />
-      <workItem from="1787832640995" duration="1220000" />
+      <workItem from="1787832640995" duration="3537000" />
     </task>
     <task id="LOCAL-00001" summary="Ajustes na documentação e remanejamento dos folders">
       <option name="closed" value="true" />
diff --git a/docs/developer/en/01_architecture_and_concepts.md b/docs/developer/en/01_architecture_and_concepts.md
index 8626bcc..898d4e8 100644
--- a/docs/developer/en/01_architecture_and_concepts.md
+++ b/docs/developer/en/01_architecture_and_concepts.md
@@ -1,91 +1,92 @@
-
 ### Agent Framework OCI Architecture and Concepts
 
 ### Purpose of this document
 
-This document **does not replace the root `README_en.md`** and does not duplicate the end-to-end agent development tutorial.
+This document **does not replace the root `README_en.md`** and does not repeat the agent-creation tutorial.
 
 Use:
 
-- [`README_en.md`](../../../README_en.md) to develop, configure, run and test an agent end to end;
-- this document to understand architecture, responsibility boundaries, components and where each implementation belongs;
-- the other manuals in this folder to deepen a specific capability or troubleshoot a problem.
+- [`README_en.md`](../../../README_en.md) to develop, configure, run, and test an agent end to end;
+- this document to understand the architecture, responsibility boundaries, components, and where each type of implementation belongs;
+- the other manuals in this folder to deepen a specific capability or solve a problem.
 
-The separation is intentional: there is **one main tutorial** and multiple **specialized reference manuals**.
+The separation is intentional: there is **one main tutorial** and several **specialized reference manuals**.
 
 ### Source of truth
 
-When documentation differs, use this order:
+When documentation diverges, use this order:
 
 1. code for the version in use;
-2. `README.md` / `README_en.md` for the same version;
+2. `README.md` / `README_en.md` from the same version;
 3. normative SPECs/SDDs;
 4. specialized manuals in this folder;
-5. release notes and `README_old*` only as historical material.
+5. release notes and `README_old*` only as history.
 
 ### Platform mental model
 
-Agent Framework OCI is a layered platform.
+Agent Framework OCI should be understood as a layered platform.
 
-The **framework core** provides reusable, domain-neutral mechanisms: runtime, state, memory, routing, tool integration, guardrails, judges, persistence, observability and common contracts.
+The **framework core** provides reusable, domain-neutral mechanisms: runtime, state, memory, routing, tool integration, guardrails, judges, persistence, observability, and common contracts.
 
-The **agent** contains use-case-specific behavior: intents, prompts, domain rules, agent-specific policies, business workflows, mappings, integrations and external components owned by that agent.
+The **agent** contains what is specific to the use case: intents, prompts, domain rules, specific policies, business workflow, mappings, integrations, and external components that belong to that agent.
 
-**Gateways** handle cross-cutting ingress, governance and integration concerns. They should not absorb agent business logic.
+**Gateways** handle cross-cutting ingress, governance, and integration responsibilities. They should not absorb the agent's business logic.
 
-**MCP Servers** encapsulate tools and integrations with domain or legacy services. The **MCP Gateway** provides centralized tool catalog and governance.
+**MCP Servers** encapsulate tools and integrations with domain or legacy services. The **MCP Gateway** provides centralized catalog and governance for these tools.
 
 ### Main components
 
-| Component | Primary responsibility | Must not contain |
+| Component | Main responsibility | Must not contain |
 |---|---|---|
-| `libs/agent_framework/` | Generic runtime, contracts, state, memory, routing, guardrails, judges and common integrations | Company- or agent-specific business rules |
-| `templates/agent_template_backend/` | Executable reference for creating agents | A permanent fork of the core |
-| `apps/agent_gateway/` | Governed ingress, cross-cutting policies, rate limits, auth and metadata | Business workflow |
-| `apps/channel_gateway/` | Adapt channels to canonical contracts | Agent business logic |
-| `apps/mcp_gateway/` | Central tool catalog, authorization and execution | Conversational orchestration |
-| `mcp/servers/` | Domain tools and integrations | Global agent orchestration |
-| `evals/` | Certification and regression | Production business logic |
-| `deploy/` | Containers and Kubernetes artifacts | Functional rules |
+| `libs/agent_framework/` | Generic runtime, contracts, state, memory, routing, guardrails, judges, common integrations | Rule specific to a company or agent |
+| `templates/agent_template_backend/` | Executable reference for creating agents | Permanent fork of the core |
+| `apps/agent_gateway/` | Governed ingress, cross-cutting policies, rate limit, authentication, metadata | Business workflow |
+| `apps/channel_gateway/` | Channel adaptation to the canonical contract | Agent business rule |
+| `apps/mcp_gateway/` | Catalog, authorization, and centralized tool execution | Conversational logic |
+| `mcp/servers/` | Integrations and tools by domain | Global agent orchestration |
+| `evals/` | Certification and regression | Production logic |
+| `deploy/` | Containers and Kubernetes | Functional rules |
 
 ### Conceptual request flow
 
+A typical request goes through the following responsibilities:
+
 ```text
-Channel
+Canal
   |
   v
 Channel Gateway
   |
   v
 Agent Gateway
-  |  governance / auth / rate limit / metadata
+  |  governança / autenticação / rate limit / metadata
   v
-Agent backend
+Backend do agente
   |
   +--> Routing / stickiness / intent
   |
-  +--> State / memory / checkpoint
+  +--> Estado / memória / checkpoint
   |
   +--> Guardrails / judges
   |
-  +--> Workflow / transaction policies
+  +--> Workflow / políticas transacionais
   |
   +--> MCP Gateway
           |
-          +--> MCP Server A --> legacy system
-          +--> MCP Server B --> external service
-          +--> MCP Server C --> domain API
+          +--> MCP Server A --> sistema legado
+          +--> MCP Server B --> serviço externo
+          +--> MCP Server C --> API de domínio
 ```
 
-Not every deployment must use every component. Composition follows agent needs and platform contracts.
+Not every deployment needs to use all components. Composition should follow the agent's needs and the platform contracts.
 
 ### Agent runtime
 
 The current runtime is based on `AgentRuntimeMixin` and `RuntimeContext`.
 
-The template imports runtime through `app.agents.runtime`, which re-exports the official framework implementation. This prevents each agent from maintaining a divergent copy.
+The template imports the runtime through `app.agents.runtime`, which re-exports the framework's official implementation. The goal is to prevent each agent from maintaining its own divergent copy of the runtime.
 
-Current APIs confirmed in this version include:
+Current APIs confirmed in the code include:
 
 ```python
 AgentRuntimeMixin.get_runtime_context()
@@ -100,11 +101,11 @@ AgentRuntimeMixin.transaction_confirmation_message()
 AgentRuntimeMixin.build_direct_mcp_answer()
 ```
 
-Developers should prefer these runtime capabilities instead of rebuilding equivalent logic inside each agent.
+These APIs represent runtime capabilities. Developers should prefer them over manually rebuilding the same logic inside each agent.
 
 ### Configuration versus code
 
-A core framework principle is to keep selectable behavior in configuration.
+A central framework guideline is that configurable behavior should remain in configuration.
 
 Examples:
 
@@ -113,130 +114,151 @@ Examples:
 - tools: `config/tools.yaml`;
 - MCP Servers and mappings: corresponding MCP configuration;
 - LLM profiles: `llm_profiles.yaml`;
-- policies and extensions: capability-specific configuration.
+- policies and extensions: capability-specific configuration files.
 
-Code implements mechanisms. YAML/config selects behavior whenever this can be done without weakening safety or contracts.
+Code should implement mechanisms. YAML/config should select behavior whenever that can be done without compromising security or contracts.
 
-### Framework versus agent responsibility
+### Separation between framework and agent
 
-A change belongs to the **framework** when it introduces a mechanism reusable by multiple agents.
+A change belongs to the **framework** when it introduces a mechanism reusable by different agents.
 
-A change belongs to the **agent** when it expresses company/domain behavior.
+Examples:
 
-If the core must import a concrete agent module to work, that boundary is probably broken.
+- new guardrail SPI;
+- new rich LLM response contract;
+- new generic checkpoint capability;
+- new configurable tool-policy mechanism;
+- new generic routing strategy.
 
-### State, memory and checkpoint are different concepts
+A change belongs to the **agent** when it expresses a rule from a domain or company.
 
-**Execution state** represents what is happening in the turn/workflow.
+Examples:
+
+- which charges can be disputed;
+- a telecom-specific prompt;
+- VAS rules;
+- internal company codes;
+- legacy-service mapping;
+- specific phraseology.
+
+If the core needs to import a concrete agent module in order to work, this separation has probably been broken.
+
+### State, memory, and checkpoint are different concepts
+
+**Execution state** represents what is happening in the turn and workflow.
 
 **Conversation memory** preserves conversational context.
 
-**Long-Term Memory** stores durable facts associated with business identity.
+**Long-Term Memory** stores durable facts associated with a business identity.
 
-**Checkpointing** persists LangGraph state snapshots for resume.
+**Checkpoint** persists LangGraph state snapshots for resume.
 
-An old checkpoint alone must not determine which transaction is active. Functional decisions should use canonical transaction state.
+An old checkpoint must not, by itself, determine which transaction is active. The functional decision must use canonical transaction state.
 
-### Routing and execution are separate responsibilities
+### Routing and execution are different responsibilities
 
-Routing answers: **which agent/intent should handle the message?**
+Routing answers: **which agent/intent should handle this message?**
 
 Execution answers: **what should that agent do now?**
 
-Route stickiness preserves continuity but must not block an explicit intent change. During a transaction, expected parameters and valid confirmation have precedence to avoid false intent shifts.
+Route stickiness preserves continuity, but it must not prevent an explicit intent change. During a transaction, expected parameters and valid confirmation take precedence to avoid false intent shifts.
 
-See [Routing, Stickiness and Intent Shift](./02_routing_stickiness_and_intent_shift.md).
+Full details: [Routing, Stickiness, and Intent Shift](./02_routing_stickiness_and_intent_shift.md).
 
 ### Tools and MCP
 
-A tool is an invokable capability.
+A tool represents an invokable capability.
 
-An MCP Server implements or exposes that capability.
+The MCP Server implements or exposes that capability.
 
-The MCP Gateway organizes catalog, authorization, mapping and centralized execution.
+The MCP Gateway organizes catalog, authorization, mapping, and centralized execution.
 
-The agent decides **when** a tool is needed; MCP determines **how** the corresponding service is accessed.
+The agent decides **when** a tool should be used in its flow; the tool/MCP decides **how** to access the corresponding service.
 
-See [MCP, Tools, Policies and Parameter Extraction](./04_mcp_integration_tools_and_policies.md).
+Full details: [MCP, Tools, Policies, and Parameter Extraction](./04_mcp_integration_tools_and_policies.md).
 
 ### Transactions
 
-Side-effecting operations require different handling from read-only queries.
+Operations with side effects require different handling from queries.
 
-The framework provides state, confirmation, policy and deterministic workflow mechanisms. Concrete domain rules remain in the agent.
+The framework provides state, confirmation, policy, and deterministic-workflow mechanisms. Concrete rules remain in the agent.
 
-An LLM may participate in interpretation and composition, but it must not be the sole source of truth for claiming that a critical operation was executed.
+The LLM may participate in interpretation and composition, but it must not be the only source of truth for claiming that a critical operation was executed.
 
-See [Transactional Workflows and State](./03_transaction_workflows_and_state.md).
+Full details: [Transactional Workflows and State](./03_transaction_workflows_and_state.md).
 
-### Guardrails and judges
+### Guardrails and Judges
 
-The core provides native mechanisms and extension points. Domain-specific guardrails/judges belong to the agent and should be loaded through configuration rather than hardcoded imports inside the core.
+Guardrails control or validate behavior during processing.
 
-See [Guardrails, Judges and Transaction Evaluation](./06_guardrails_judges_and_transaction_evaluation.md).
+Judges evaluate quality, grounding, and other criteria.
 
-### RAG, memory and tools are not interchangeable
+The core provides native mechanisms and extension points. Domain-specific guardrails/judges should be loaded by the agent through configuration, avoiding specific imports inside the framework.
+
+Full details: [Guardrails, Judges, and Transaction Evaluation](./06_guardrails_judges_and_transaction_evaluation.md).
+
+### RAG, memory, and tools are not equivalent
 
 - **RAG** retrieves knowledge.
 - **Memory** preserves context/facts.
-- **Tools** query or execute external capabilities.
+- **Tool** executes or queries an external capability.
 
-Using the wrong mechanism creates difficult-to-diagnose behavior.
+Choosing the wrong mechanism creates bugs that are difficult to diagnose. Information that needs to be updated in a system should not be solved only through RAG; a durable customer fact should not depend only on prompt history.
 
 ### Observability as a cross-cutting contract
 
-Routing, agent, transaction, tool, guardrail, judge and failure events must be correlatable.
+Routing, agent, transaction, tool, guardrail, judge, and failure must be correlatable.
 
-Observability records what happened; it must not become business-state control.
+Observability should record what happened, but it must not control business state. Sequence, trace IDs, and labels are diagnostic and audit infrastructure.
 
-See [Observability, Persistence and Operational Readiness](./11_observability_persistence_and_operational_readiness.md).
+Full details: [Observability, Persistence, and Operational Readiness](./11_observability_persistence_and_operational_readiness.md).
 
-### Where a new feature belongs
+### Where to place a new feature
 
-Before implementing a feature, ask:
+Before implementing, ask these questions:
 
-1. Is it reusable by multiple agents?
-2. Does it contain domain-specific rules?
-3. Does it require state across turns?
+1. Is the capability reusable by different agents?
+2. Is there a domain-specific rule?
+3. Does it need state across turns?
 4. Does it produce side effects?
 5. Does it depend on an external system?
 6. Should it be configurable?
-7. Must it be observable?
-8. Must a guardrail/judge evaluate it?
+7. Does it need to appear in observability?
+8. Does it need to be evaluated by a guardrail/judge?
 
-A reusable capability normally starts in the core and is enabled/configured by the agent. A business rule normally starts in the agent and uses core interfaces.
+A reusable feature normally starts in the core and is enabled/configured by the agent. A business rule normally starts in the agent and uses core interfaces.
 
 ### Anti-patterns
 
 Avoid:
 
 - importing a concrete agent package inside the core;
-- duplicating `AgentRuntimeMixin` per agent;
-- hardcoding agent, intent, tool or company names in runtime;
-- treating LLM output as proof of operation execution;
-- treating an old checkpoint as the active transaction;
-- executing transactional operations without required policy/confirmation;
-- directly coupling agents to many services when MCP Gateway is the intended layer;
+- duplicating `AgentRuntimeMixin` in every agent;
+- hardcoding agent, intent, tool, or company names in the runtime;
+- using an LLM response as proof that an operation was executed;
+- confusing an old checkpoint with the active transaction;
+- executing a transactional operation without policy/confirmation when it is required;
+- coupling an agent directly to dozens of services when MCP Gateway is the intended layer;
 - creating a new functional document for every bug fix instead of updating the feature manual.
 
 ### Recommended path for a new developer
 
-1. Read this architecture overview.
-2. Follow [`README_en.md`](../../../README_en.md) end to end.
-3. Use the specialized manual when reaching a specific capability.
-4. For failures, start from the [Developer Index](./INDEX_DEVELOPER_GUIDE.md), under **Search by problem**.
-5. Before copying historical code, confirm the API/import in the current template and core.
+1. Read the architectural overview in this document.
+2. Follow [`README_en.md`](../../../README_en.md) from beginning to end to create and run an agent.
+3. When you reach a specific capability, use the corresponding specialized manual.
+4. For failures, start with the [Developer Index](./INDEX_DEVELOPER_GUIDE.md), in the **Search by problem** section.
+5. Before copying old code, confirm the API/import in the current template and core.
 
 ### Related documents
 
-- [Main tutorial — README_en.md](../../../README_en.md)
-- [Routing, Stickiness and Intent Shift](./02_routing_stickiness_and_intent_shift.md)
+- [Main tutorial — README.md](../../../README.md)
+- [Routing, Stickiness, and Intent Shift](./02_routing_stickiness_and_intent_shift.md)
 - [Transactional Workflows and State](./03_transaction_workflows_and_state.md)
-- [MCP, Tools, Policies and Parameters](./04_mcp_integration_tools_and_policies.md)
+- [MCP, Tools, Policies, and Parameters](./04_mcp_integration_tools_and_policies.md)
 - [Gateways and Authentication](./05_agent_gateway_mcp_gateway_and_auth.md)
 - [Guardrails and Judges](./06_guardrails_judges_and_transaction_evaluation.md)
 - [RAG and BusinessContext](./07_rag_business_context_and_grounding.md)
 - [Long-Term Memory and Checkpoint](./08_long_term_memory_and_checkpoint.md)
 - [LLM Rich Response](./09_llm_rich_response_reasoning.md)
-- [Performance, Cache and Async Runtime](./10_performance_cache_and_async_runtime.md)
+- [Performance, Cache, and Async Runtime](./10_performance_cache_and_async_runtime.md)
 - [Observability and Operational Readiness](./11_observability_persistence_and_operational_readiness.md)
diff --git a/docs/developer/en/02_routing_stickiness_and_intent_shift.md b/docs/developer/en/02_routing_stickiness_and_intent_shift.md
index 11383e3..61e377e 100644
--- a/docs/developer/en/02_routing_stickiness_and_intent_shift.md
+++ b/docs/developer/en/02_routing_stickiness_and_intent_shift.md
@@ -1,63 +1,809 @@
-
 ### Routing, Route Stickiness and Intent Shift
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **routing, stickiness, intent shifts, deterministic/LLM routing and multi-agent isolation**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **routing, stickiness, intent changes, deterministic/LLM routing, and multi-agent isolation**.
+- The historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Routing, stickiness, intent shifts, deterministic/llm routing and multi-agent isolation.
+Routing, stickiness, intent changes, deterministic/LLM routing, and multi-agent isolation.
 
 ### Consolidated technical content
 
-### Multi-Agent Routing, Route Stickiness and Intent Shift
+### Multi-Agent Routing, Route Stickiness, and Intent Shift
 
-This guide defines how the platform selects an agent, preserves continuity and handles an explicit change of intent without trapping the user in the previous route.
+Complete manual for route decision, Enterprise Router, Supervisor, semantic continuity, global session actions, explicit intent changes, and precedence during transactions.
 
-### Routing modes
+### How to use this document
 
-The template supports two architectural modes. **Enterprise Router** performs a routing decision and invokes the selected agent. **Supervisor** uses a supervisor node to coordinate the next agent. The mode is configuration-driven; domain agents should not reimplement routing infrastructure.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### Enterprise routing decision order
+### Multi-agent routing manual
 
-Routing should use the cheapest reliable signal first. Deterministic mappings/signals may resolve known intents. If deterministic discovery does not produce a valid route and LLM routing is enabled, the router can ask the configured routing model. This keeps LLM routing as a semantic capability without forcing every turn through an LLM.
+> Content consolidated from `Documentacao/Manual de Roteamento Multi-Agent.docx`.
 
-### Semantic route stickiness
+Multi-Agent Routing Manual  
+Agent Gateway (Global Supervisor), Enterprise Router, and Supervisor in the `agent_framework_oci` project
 
-Route stickiness is a lightweight session-control classification executed before normal routing. It can return:
+### Table of contents
 
-- `CONTINUE`: keep the active agent.
-- `ROUTE`: execute normal Enterprise Router logic.
-- `HUMAN_HANDOFF`: enter the global human-handoff node.
-- `END_SESSION`: enter the global session-ending node.
+- 1. Purpose of the manual
+- 2. What routing means in a multi-agent backend
+- 3. Why routing should be structured for scale, simplicity, and performance
+- 4. Actual project folder structure
+- 5. Architecture overview
+- 6. Main routing components
+- 7. Routing types available in the project
+- 8. Path 1 - Implement agents with Enterprise Router
+- 9. Path 2 - Implement agents with Supervisor
+- 10. How to configure agents, intents, MCP tools, and conversational state
+- 11. How LangGraph executes routing
+- 12. End-to-end functional examples
+- 13. How to test with curl
+- 14. Observability, memory, and checkpointing
+- 15. Troubleshooting
+- 16. Implementation checklist
+- 17. Separate Agent Servers (Global Supervisor or Agent Gateway)
 
-The classifier does not answer the user and does not call tools. Low confidence, timeout, invalid JSON or classifier failure falls back to normal routing. `CONTINUE` is valid only when there is an active agent; otherwise it is treated as `ROUTE`.
+### Purpose of the manual
+
+This manual explains how multi-agent routing is implemented in the `agent_framework_oci` project and how to evolve the backend with new agents without losing governance, performance, and traceability.  
+The components are distributed between the reusable `agent_framework` package and the FastAPI `agent_template_backend` template.
+
+### What routing means in a multi-agent backend
+
+Routing is the step that transforms a user message into an operational decision: which agent should answer, with which intent, which MCP tools may be used, which domain is involved, and which context must be preserved.  
+In a multi-agent system, routing is equivalent to traffic control. Without it, all agents become mixed into the same prompt, memory can be contaminated by different subjects, latency increases, and observability becomes confusing.
+
+### Why routing should be structured for scale, simplicity, and performance
+
+Routing is not only a functional decision. It is an architectural decision. The way the backend selects agents affects cost, latency, testing, governance, telemetry, and product evolution.
+
+### Actual project folder structure
+
+The current structure has three main blocks: reusable framework, backend template, and example MCP servers.
+```
+agent_framework_oci/
+  agent_framework/
+    src/agent_framework/
+      routing/
+        config_loader.py
+        enterprise_router.py
+        models.py
+      supervisor/
+        supervisor.py
+      mcp/
+        tool_router.py
+        registry.py
+        client.py
+        models.py
+      config/
+        settings.py
+        agent_registry.py
+      guardrails/
+      judges/
+      memory/
+      checkpoints/
+      observability/
+      events/
+
+  agent_template_backend/
+    app/
+      main.py
+      state.py
+      workflows/
+        agent_graph.py
+      agents/
+        billing_agent.py
+        product_agent.py
+        orders_agent.py
+        support_agent.py
+        runtime.py
+        prompting.py
+    config/
+      agents.yaml
+      routing.yaml
+      mcp_servers.yaml
+      mcp_servers.docker.yaml
+      tools.yaml
+      guardrails.yaml
+      judges.yaml
+      prompt_policy.yaml
+      agents/
+        telecom_contas/
+        retail_orders/
+
+  mcp_servers/
+    telecom_mcp_server/main.py
+    retail_mcp_server/main.py
+
+  agent_frontend/
+    index.html
+    app.js
+    styles.css
+
+  docker-compose.yml
+  scripts/
+    run_backend.sh
+    run_frontend.sh
+    run_mcp_servers.sh
+    smoke_usage_test.sh
+```
+
+### Architecture overview
+
+The backend uses FastAPI as the entry layer, ChannelGateway for message normalization, LangGraph for orchestration, EnterpriseRouter or Supervisor for routing decisions, specialist agents for execution, MCPToolRouter for external tools, and guardrail, judge, memory, checkpoint, and observability layers.
+```
+User / Frontend / Canal
+        |
+        v
+FastAPI - agent_template_backend/app/main.py
+        |
+        v
+ChannelGateway normaliza payload
+        |
+        v
+SessionRepository + MemoryRepository
+        |
+        v
+AgentWorkflow - app/workflows/agent_graph.py
+        |
+        +--> input_guardrails
+        |
+        +--> routing_decision
+        |       |-- ROUTING_MODE=router     -> EnterpriseRouter
+        |       |-- ROUTING_MODE=supervisor -> Supervisor.route_plan
+        |
+        +--> agente especialista ou supervisor_agent
+        |       |-- billing_agent
+        |       |-- product_agent
+        |       |-- orders_agent
+        |       |-- support_agent
+        |       +-- MCPToolRouter -> MCP Servers telecom/retail
+        |
+        +--> output_guardrails
+        +--> judge
+        +--> supervisor_review
+        +--> persist
+        |
+        v
+Resposta + metadata + trace + checkpoint + eventos
+```
+
+### Main routing components
+
+
+### Settings
+
+The file `agent_framework/src/agent_framework/config/settings.py` centralizes the variables that enable routing, MCP, observability, repositories, LLM, and cache.
+```
+ROUTING_MODE: Literal['router','supervisor'] = 'router'
+ROUTING_CONFIG_PATH: str = './config/routing.yaml'
+ENABLE_LLM_ROUTER: bool = False
+ENABLE_MCP_TOOLS: bool = True
+MCP_SERVERS_CONFIG_PATH: str = './config/mcp_servers.yaml'
+TOOLS_CONFIG_PATH: str = './config/tools.yaml'
+SESSION_REPOSITORY_PROVIDER: Literal['memory','sqlite','autonomous','oracle','mongodb'] = 'memory'
+MEMORY_REPOSITORY_PROVIDER: Literal['memory','sqlite','autonomous','oracle','mongodb'] = 'memory'
+CHECKPOINT_REPOSITORY_PROVIDER: Literal['memory','sqlite','autonomous','oracle','mongodb'] = 'memory'
+ENABLE_LANGFUSE: bool = False
+```
+
+### RouteDecision
+
+`RouteDecision` is the EnterpriseRouter output contract. It carries the functional decision as well as information useful for audit and tool execution.
+```
+class RouteDecision(BaseModel):
+    route: str
+    agent: str
+    intent: str
+    confidence: float = 0.0
+    reason: str = ''
+    method: Literal['state','keyword','llm','fallback'] = 'fallback'
+    next_state: str | None = None
+    handoff: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    domain: str | None = None
+    mcp_tools: list[str] = Field(default_factory=list)
+```
+
+### IntentDefinition
+
+`IntentDefinition` is loaded from `config/routing.yaml` and describes a routable intent.
+
+### SupervisorPlan
+
+`SupervisorPlan` is the Supervisor output contract. Instead of returning a single agent, it returns a list of agents to execute in the `supervisor_agent` node.
+```
+@dataclass
+class SupervisorPlan:
+    agents: list[str]
+    intent: str
+    confidence: float = 0.0
+    reason: str = ''
+    metadata: dict[str, Any] = field(default_factory=dict)
+```
+
+### Routing types available in the project
+
+
+### Enterprise Router
+
+The EnterpriseRouter executes a clear decision order: conversational state, keyword/intents, optional LLM, and fallback. This order is important because it prevents short messages such as "yes" from being classified outside the active flow.
+```
+Fluxo do EnterpriseRouter:
+1. current_state = state.next_state ou session.metadata.workflow_state
+2. Se state_policies contém o estado, retorna o agente associado
+3. Caso contrário, procura keywords nas intents habilitadas
+4. Se ENABLE_LLM_ROUTER=true, pede classificação ao LLM
+5. Se nada funcionar, usa router.fallback_agent
+```
+
+### Supervisor
+
+The implemented Supervisor is deterministic. It looks for billing, product, orders, and support keywords. If it detects more than one domain, it returns `intent=multi_intent` and multiple agents. The workflow then executes `supervisor_agent`, which calls the specified agents and consolidates the response.
+```
+Mensagem: "Meu pedido atrasou e minha fatura veio duplicada"
+SupervisorPlan:
+  agents: ["billing_agent", "orders_agent"]
+  intent: "multi_intent"
+  reason: "Supervisor detectou múltiplas intenções e acionará mais de um agente."
+```
+
+### Path 1 - Implement agents with Enterprise Router
+
+This is the recommended path for initial production. Each turn selects one primary agent. The design is simple, performant, and easy to observe.
+```
+Usuário
+  -> input_guardrails
+  -> routing_decision
+       -> EnterpriseRouter.route(state)
+            -> state_policies
+            -> keyword/intents
+            -> LLM opcional
+            -> fallback
+  -> billing_agent | product_agent | orders_agent | support_agent
+  -> output_guardrails
+  -> judge
+  -> supervisor_review
+  -> persist
+```
+
+### Step 1 - Define the mode in `.env`
+
+```
+ROUTING_MODE=router
+ROUTING_CONFIG_PATH=./config/routing.yaml
+ENABLE_LLM_ROUTER=false
+ENABLE_MCP_TOOLS=true
+```
+
+### Step 2 - Register or adjust the intent in `config/routing.yaml`
+
+Each intent must point to the specialist agent and list the MCP tools authorized for that intent.
+```
+intents:
+  - name: billing_invoice_explanation
+    domain: telecom
+    agent: billing_agent
+    description: Dúvidas sobre fatura, cobrança, vencimento, segunda via, contestação e valores.
+    priority: 10
+    mcp_tools:
+      - consultar_fatura
+      - consultar_pagamentos
+    keywords:
+      - fatura
+      - conta
+      - cobrança
+      - boleto
+      - vencimento
+      - segunda via
+      - contestar
+      - valor alto
+```
+
+### Step 3 - Ensure that the agent exists in the workflow
+
+In the current project, agents are instantiated directly in `AgentWorkflow.__init__` and have also been added as LangGraph nodes.
+```
+# agent_template_backend/app/workflows/agent_graph.py
+self.billing = BillingAgent(llm, **agent_kwargs)
+self.product = ProductAgent(llm, **agent_kwargs)
+self.orders = OrdersAgent(llm, **agent_kwargs)
+self.support = SupportAgent(llm, **agent_kwargs)
+
+builder.add_node("billing_agent", self._node("billing_agent", self.billing_agent))
+builder.add_node("product_agent", self._node("product_agent", self.product_agent))
+builder.add_node("orders_agent", self._node("orders_agent", self.orders_agent))
+builder.add_node("support_agent", self._node("support_agent", self.support_agent))
+```
+
+### Step 4 - Ensure that the graph conditional accepts the route
+
+```
+builder.add_conditional_edges(
+    "routing_decision",
+    lambda s: s.get("route", "billing_agent"),
+    {
+        "billing_agent": "billing_agent",
+        "product_agent": "product_agent",
+        "orders_agent": "orders_agent",
+        "support_agent": "support_agent",
+        "handoff": "handoff",
+        "supervisor_agent": "supervisor_agent",
+    },
+)
+```
+
+### Step 5 - Configure the intent's MCP tools
+
+The intent carries `mcp_tools` in the `RouteDecision`. The agent reads `state.get("mcp_tools")` and calls `self.tool_router.call(tool, args)`.
+```
+# Exemplo em BillingAgent._collect_tool_context
+tools = state.get("mcp_tools") or []
+for tool in tools:
+    args = {
+        "msisdn": ctx.get("msisdn"),
+        "invoice_id": ctx.get("invoice_id"),
+        "asset_id": ctx.get("asset_id"),
+        "session_id": state.get("conversation_key") or state.get("session_id"),
+    }
+    res = await self.tool_router.call(tool, args)
+```
+
+### Path 2 - Implement agents with Supervisor
+
+This path is appropriate when the user may mix subjects in a single message. The Supervisor does not choose only one route; it creates an execution plan.
+```
+Usuário
+  -> input_guardrails
+  -> routing_decision
+       -> Supervisor.route_plan(state)
+       -> route = supervisor_agent
+  -> supervisor_agent
+       -> executa billing_agent opcional
+       -> executa product_agent opcional
+       -> executa orders_agent opcional
+       -> executa support_agent opcional
+       -> consolida resposta
+  -> output_guardrails
+  -> judge
+  -> supervisor_review
+  -> persist
+```
+
+### Step 1 - Enable it in `.env`
+
+```
+ROUTING_MODE=supervisor
+ENABLE_SUPERVISOR=true
+ENABLE_MCP_TOOLS=true
+```
+
+### Step 2 - Adjust Supervisor rules
+
+In the current project, the Supervisor uses the `ROUTING_RULES` list in `agent_framework/src/agent_framework/supervisor/supervisor.py`. To include a new agent in supervisor mode, add a rule with intent, agent, and keywords.
+```
+ROUTING_RULES = [
+    ("billing", "billing_agent", ["fatura", "conta", "cobrança", "boleto"]),
+    ("product", "product_agent", ["produto", "plano", "serviço", "internet"]),
+    ("orders", "orders_agent", ["pedido", "entrega", "rastreio", "atraso"]),
+    ("support", "support_agent", ["troca", "devolução", "garantia", "defeito"]),
+]
+```
+
+### Step 3 - Ensure that `supervisor_agent` knows how to execute the agent
+
+```
+handlers = {
+    "billing_agent": self.billing.run,
+    "product_agent": self.product.run,
+    "orders_agent": self.orders.run,
+    "support_agent": self.support.run,
+}
+
+for agent_name in agents:
+    handler = handlers.get(agent_name)
+    child_state = {**state, "route": agent_name, "active_agent": agent_name}
+    result = await handler(child_state)
+```
+
+### Step 4 - Understand consolidation
+
+When the Supervisor activates only one agent, the final response is that agent's response. When it activates several, the current project concatenates partial responses with a consolidation prefix. In production, this step can evolve into an LLM synthesis with its own prompt and specific guardrails.
+```
+if len(partials) == 1:
+    answer = partials[0]["answer"]
+else:
+    joined = "
+
+".join(f"{p['agent']}: {p['answer']}" for p in partials)
+    answer = "[Supervisor] Consolidação de múltiplos agentes acionados.
+" + joined
+```
+
+### How to configure agents, intents, MCP tools, and conversational state
+
+
+### `config/agents.yaml`
+
+This file does not directly register each specialist node. It registers agent profiles/templates, such as `telecom_contas` and `retail_orders`. The input `agent_id` defines the isolation context, policies, prompts, guardrails, judges, and tools.
+```
+default_agent_id: telecom_contas
+agents:
+  - agent_id: telecom_contas
+    name: Agente Telecom Contas
+    prompt_policy_path: ./config/agents/telecom_contas/prompt_policy.yaml
+    routing_config_path: ./config/routing.yaml
+    guardrails_config_path: ./config/agents/telecom_contas/guardrails.yaml
+    judges_config_path: ./config/agents/telecom_contas/judges.yaml
+    mcp_servers_config_path: ./config/mcp_servers.yaml
+    tools_config_path: ./config/tools.yaml
+    metadata:
+      domain: telecom
+
+  - agent_id: retail_orders
+    name: Agente Retail Pedidos
+    prompt_policy_path: ./config/agents/retail_orders/prompt_policy.yaml
+    routing_config_path: ./config/routing.yaml
+    guardrails_config_path: ./config/agents/retail_orders/guardrails.yaml
+    judges_config_path: ./config/agents/retail_orders/judges.yaml
+    mcp_servers_config_path: ./config/mcp_servers.yaml
+    tools_config_path: ./config/tools.yaml
+    metadata:
+      domain: retail
+```
+
+### `config/routing.yaml`
+
+This file configures the EnterpriseRouter and documents the default mode. The `.env` variable `ROUTING_MODE` is the recommended way to enable router or supervisor at runtime.
+
+### `config/tools.yaml`
+
+Defines each logical tool and the responsible MCP server.
+```
+tools:
+  consultar_fatura:
+    description: Consulta dados resumidos de fatura por msisdn/invoice_id.
+    mcp_server: telecom
+    enabled: true
+    args_schema:
+      msisdn: string
+      invoice_id: string
+
+  consultar_pedido:
+    description: Consulta pedido de varejo por order_id/customer_id.
+    mcp_server: retail
+    enabled: true
+    args_schema:
+      order_id: string
+      customer_id: string
+```
+
+### `config/mcp_servers.yaml`
+
+```
+servers:
+  telecom:
+    transport: http
+    endpoint: http://localhost:8100/mcp
+    enabled: true
+    description: MCP Server de exemplo para domínio Telecom.
+
+  retail:
+    transport: http
+    endpoint: http://localhost:8200/mcp
+    enabled: true
+    description: MCP Server de exemplo para domínio Retail.
+```
+
+### How LangGraph executes routing
+
+The graph is created in `agent_template_backend/app/workflows/agent_graph.py`. The key point is that there is a single decision node: `routing_decision`. This avoids having two different backends for the two routing models.
+```
+START
+  -> input_guardrails
+  -> routing_decision
+      -> billing_agent
+      -> product_agent
+      -> orders_agent
+      -> support_agent
+      -> handoff
+      -> supervisor_agent
+  -> output_guardrails
+  -> judge
+  -> supervisor_review
+  -> persist
+  -> END
+```
+
+### End-to-end functional examples
+
+
+### Router example - invoice
+
+```
+Entrada:
+"Minha fatura veio alta"
+
+EnterpriseRouter:
+- Lê sanitized_input
+- Encontra keyword "fatura"
+- Seleciona intent billing_invoice_explanation
+- Retorna route=billing_agent
+- Retorna mcp_tools=[consultar_fatura, consultar_pagamentos]
+
+Workflow:
+- Vai para billing_agent
+- BillingAgent chama MCPToolRouter para consultar_fatura/consultar_pagamentos se houver argumentos no contexto
+- Resposta passa por output_guardrails, judges, supervisor_review e persist
+```
+
+### Router example - order
+
+```
+Entrada:
+"Onde está meu pedido?"
+
+EnterpriseRouter:
+- Keyword "pedido"
+- Intent retail_order_tracking
+- Route orders_agent
+- Tools consultar_pedido e consultar_entrega
+
+Workflow:
+- Executa OrdersAgent
+- OrdersAgent monta argumentos order_id/customer_id a partir do context
+- Chama tools MCP de retail quando disponíveis
+```
+
+### Supervisor example - billing + order
+
+```
+Entrada:
+"Meu pedido atrasou e minha fatura veio duplicada"
+
+Supervisor:
+- Detecta pedido/atraso -> orders_agent
+- Detecta fatura/duplicada -> billing_agent
+- Retorna agents=[billing_agent, orders_agent] ou ordem conforme regras
+- intent=multi_intent
+
+Workflow:
+- routing_decision retorna route=supervisor_agent
+- supervisor_agent executa cada agente listado
+- Consolida resposta final
+- Output guardrails e judges avaliam a resposta consolidada
+```
+
+### How to test with curl
+
+
+### Check backend and active mode
+
+```
+curl http://localhost:8000/health | jq
+Campos importantes esperados:
+{
+  "status": "ok",
+  "routing_mode": "router" ou "supervisor",
+  "agents": ["telecom_contas", "retail_orders"],
+  "session_repository": "memory|sqlite|autonomous|oracle|mongodb",
+  "checkpoint_repository": "memory|sqlite|autonomous|oracle|mongodb"
+}
+```
+
+### Check loaded agents/profiles
+
+```
+curl http://localhost:8000/agents | jq
+```
+
+### Test routing without executing the full conversation
+
+```
+curl -X POST http://localhost:8000/debug/route   -H 'Content-Type: application/json'   -d '{
+    "channel":"web",
+    "payload":{
+      "text":"Minha fatura veio alta",
+      "session_id":"s-router-1",
+      "context":{"msisdn":"5511999999999","invoice_id":"INV001"}
+    },
+    "agent_id":"telecom_contas",
+    "tenant_id":"tenant_a"
+  }' | jq
+Resposta esperada em ROUTING_MODE=router:
+{
+  "route": "billing_agent",
+  "agent": "billing_agent",
+  "intent": "billing_invoice_explanation",
+  "method": "keyword",
+  "mode": "router",
+  "mcp_tools": ["consultar_fatura", "consultar_pagamentos"]
+}
+curl -X POST http://localhost:8000/debug/route   -H 'Content-Type: application/json'   -d '{
+    "channel":"web",
+    "payload":{
+      "text":"Meu pedido atrasou e minha fatura veio duplicada",
+      "session_id":"s-supervisor-1",
+      "context":{"order_id":"P100","msisdn":"5511999999999"}
+    },
+    "agent_id":"telecom_contas",
+    "tenant_id":"tenant_a"
+  }' | jq
+Resposta esperada em ROUTING_MODE=supervisor:
+{
+  "mode": "supervisor",
+  "route": "supervisor_agent",
+  "agents": ["billing_agent", "orders_agent"],
+  "intent": "multi_intent"
+}
+```
+
+### Test MCP tools
+
+```
+curl http://localhost:8000/debug/mcp/tools | jq
+
+curl -X POST http://localhost:8000/debug/mcp/call/consultar_fatura   -H 'Content-Type: application/json'   -d '{"msisdn":"5511999999999","invoice_id":"INV001"}' | jq
+
+curl -X POST http://localhost:8000/debug/mcp/call/consultar_pedido   -H 'Content-Type: application/json'   -d '{"order_id":"P100","customer_id":"C001"}' | jq
+```
+
+### Test the full conversation
+
+```
+curl -X POST http://localhost:8000/gateway/message   -H 'Content-Type: application/json'   -d '{
+    "channel":"web",
+    "agent_id":"telecom_contas",
+    "tenant_id":"tenant_a",
+    "payload":{
+      "text":"Minha fatura veio alta. Pode consultar?",
+      "session_id":"web-001",
+      "user_id":"u1",
+      "channel_id":"browser-1",
+      "context":{
+        "msisdn":"5511999999999",
+        "invoice_id":"INV001"
+      }
+    }
+  }' | jq
+Campos úteis na resposta:
+metadata.route
+metadata.intent
+metadata.route_decision
+metadata.mcp_tools
+metadata.mcp_results
+metadata.guardrails
+metadata.judges
+```
+
+### Observability, memory, and checkpointing
+
+The input flow creates an identity with `tenant_id`, `agent_id`, and `session_id`. The `AgentIdentity.conversation_key()` method is used as the operational conversation key. This key is used for session, memory, checkpoint, SSE, and telemetry.
+```
+tenant_id + agent_id + session_id -> conversation_key
+Exemplo:
+tenant_a:telecom_contas:web-001
+Endpoints úteis:
+GET /sessions/{session_id}/messages
+GET /sessions/{session_id}/checkpoint
+GET /debug/usage
+GET /debug/env
+```
+
+### Troubleshooting
+
+
+### Implementation checklist
+
+- Decide whether the use case requires `ROUTING_MODE=router` or `ROUTING_MODE=supervisor`.
+- Register or adjust intents in `agent_template_backend/config/routing.yaml`.
+- Ensure each intent points to the correct specialist agent.
+- Configure `mcp_tools` on the intent only when the tool should be allowed in that context.
+- Register tools in `config/tools.yaml` and servers in `config/mcp_servers.yaml`.
+- Ensure the specialist agent exists in `agent_template_backend/app/agents/`.
+- Instantiate the agent in `AgentWorkflow.__init__`.
+- Add the agent node to LangGraph.
+- Add the route to `routing_decision`'s `add_conditional_edges`.
+- In supervisor mode, add a rule to `Supervisor.ROUTING_RULES` and a handler to `supervisor_agent`.
+- Test `/health`, `/agents`, and `/debug/env`.
+- Test `/debug/route` for each intent.
+- Test `/debug/mcp/tools` and `/debug/mcp/call/{tool_name}`.
+- Test `/gateway/message` with real context.
+- Check `metadata.route`, `metadata.intent`, `metadata.route_decision`, `metadata.mcp_results`, guardrails, and judges.
+- Validate memory, checkpoint, and traces by `conversation_key`.
+
+### Architecture — Global Supervisor
+
+```text
+User / Frontend
+        │
+        ▼
+┌───────────────────────────────┐
+│ Agent Gateway                 │
+│ Global Supervisor             │
+│                               │
+│ - Rule-based router           │
+│ - LLM-based supervisor        │
+│ - Stateful hybrid             │
+│ - Handoff between backends    │
+└───────────────┬───────────────┘
+                │
+      ┌─────────┼─────────┬────────────┐
+      ▼         ▼         ▼            ▼
+Backend      Backend   Backend     Backend
+Billing      Offers    Support     Collections
+```
+Each backend remains an independent project, with its own agents, prompts, MCPs, and deployment, but all of them use the same `agent_framework` library.
+
+### Global state
+
+The Gateway maintains an `active_backend` for each `session_id`. In `hybrid` mode, short messages such as `"and this amount?"` remain on the active backend without calling the LLM.
+
+### Shared memory
+
+For production, configure the backends to use the same Session/Memory/Checkpoint Repository, preferably Autonomous DB, Oracle, MongoDB, or Redis + DB.
+
+### Semantic Route Stickiness and global session control
+
+> Content consolidated from `Documentacao/Route_Stickiness_Semantica_Agent_Framework_OCI.docx`.
+
+Agent Framework OCI  
+Lightweight LLM classification, without regex, with Human Handoff and Session End
+
+### Goal
+
+The capability uses a lightweight LLM profile to decide global turn handling without regex, phrase lists, or domain-specific linguistic rules. It prevents each agent from implementing its own continuity, human transfer, or termination logic.
+- CONTINUE: keeps the active agent.
+- ROUTE: executes the normal Enterprise Router.
+- HUMAN_HANDOFF: requests human assistance.
+- END_SESSION: ends automated service.
+
+### Architectural principles
+
+- No natural-language rule is coded in the core.
+- The classifier does not answer the user and does not execute tools.
+- Handoff and session ending are handled by global graph nodes.
+- Low confidence, timeout, error, or invalid JSON fall back to the Enterprise Router.
+- CONTINUE requires an active agent; without an active agent, the decision becomes ROUTE.
+
+### Flow
+
+Message -> Lightweight LLM classifier  
+  CONTINUE + active agent -> current agent  
+  ROUTE / low confidence / error -> Enterprise Router  
+  HUMAN_HANDOFF -> `human_handoff` node  
+  END_SESSION -> `end_session` node  
+Global actions can be recognized on the first turn. This allows “I want to talk to a person” or “you can end the session” not to depend on a domain agent having already been selected.
 
 ### Configuration
 
+
+### `.env`
+
 ```env
 ENABLE_ROUTE_STICKINESS=true
 ROUTE_STICKINESS_LLM_PROFILE=route_continuity
 ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
 ROUTE_STICKINESS_HISTORY_TURNS=2
 ROUTE_STICKINESS_MAX_TOKENS=80
-HUMAN_HANDOFF_MESSAGE=I will transfer your interaction to a person.
-END_SESSION_MESSAGE=Interaction ended. Thank you.
+HUMAN_HANDOFF_MESSAGE=I will transfer your service to a person.
+END_SESSION_MESSAGE=Service ended. Thank you for contacting us.
 ```
 
-Example lightweight profile:
+### `llm_profiles.yaml`
 
 ```yaml
 profiles:
@@ -68,761 +814,633 @@ profiles:
     max_tokens: 80
     timeout_seconds: 5
 ```
+The model is only an example. Use the smallest approved model available in the OCI environment.
 
-Use the smallest approved model that reliably classifies continuity in the target environment.
+### Output contracts
 
-### Why deterministic intent shift still exists
 
-Semantic stickiness cannot be allowed to suppress an explicit user request that clearly targets a different operation. Recent fixes introduced deterministic preemption for unequivocal intent changes before invoking the continuity LLM. This is a performance and correctness optimization, not a replacement for semantic routing.
+### Continuity
 
-Typical examples include moving from an informational query to a transactional action or from one tool-backed operation to another within the same agent.
+{"decision":"CONTINUE","confidence":0.97,"reason":"Continuação do assunto anterior."}
+With sufficient confidence and an active agent, the router returns `method=continuity` and `route_bypassed=true`.
 
-### Routing precedence during an open transaction
+### Human handoff
 
-An open transaction changes precedence. If the transaction is waiting for a required parameter and the user's message supplies that parameter, parameter extraction/merge wins over intent-shift detection. If the transaction is waiting for confirmation and the user provides an accepted confirmation/rejection, the transaction state machine wins. Only a genuinely explicit unrelated request should interrupt/reroute according to policy.
+{"route":"human_handoff","intent":"human_handoff","handoff":true,
+ "metadata":{"session_control":"HUMAN_HANDOFF","route_bypassed":true}}
+- `session_control=HUMAN_HANDOFF`
+- `human_handoff_requested=true`
+- `session_ended=false`
+- `next_state=HUMAN_HANDOFF_REQUESTED`
+- event `session.human_handoff.requested`
+The client integration remains responsible for selecting the queue, human-assistance platform, and transfer protocol.
 
-This prevents values such as a price, invoice identifier or product name from being mistaken for a new intent.
+### Session end
 
-### Global session-control contracts
+{"route":"end_session","intent":"end_session",
+ "metadata":{"session_control":"END_SESSION","route_bypassed":true}}
+- `session_control=END_SESSION`
+- `session_ended=true`
+- `human_handoff_requested=false`
+- `next_state=SESSION_ENDED`
+- event `session.end.requested`
+Physical connection closing, TTL, or session expiration remains the responsibility of the channel or backend.
 
-Human handoff should set a route/intent representing handoff, mark the request in metadata/state and emit the corresponding observability event. Selecting the actual human queue or platform remains an external channel/integration responsibility.
+### Examples
 
-End-session should mark the session as ended and emit the global event. Physically closing an SSE/HTTP/voice/WhatsApp connection and applying TTL/expiration policy remains the responsibility of the channel/backend.
 
-### Failure behavior
+### Files changed
 
-- No active agent + `CONTINUE` → route normally.
-- Low classifier confidence → route normally.
-- Classifier timeout/error/invalid output → route normally.
-- Explicit deterministic intent shift → do not let stickiness override it.
-- Valid transaction parameter/confirmation → continue transaction before rerouting.
-
-### Testing
-
-Regression coverage should include continuity, domain change, first-turn handoff, first-turn end-session, low confidence, invalid model output, no active agent, explicit intent shift within the same agent, informational→transactional shift and active-transaction parameter precedence.
-
-### Troubleshooting
-
-If the route never changes, inspect the active agent, route-stickiness decision/confidence, deterministic intent-shift signal and current transaction state. If every turn reroutes, verify that the active-agent/session state is being persisted and that the continuity classifier receives the configured history. If routing makes unnecessary LLM calls, verify deterministic discovery/intent-shift is enabled before semantic fallback.
-
-### Source material consolidated
-
-- `Documentacao/Manual de Roteamento Multi-Agent.docx`
-- `Documentacao/Route_Stickiness_Semantica_Agent_Framework_OCI.docx`
-- `Documentacao/README_ROUTING_MODES.md`
-- `Documentacao/README_ENTERPRISE_ROUTING.md`
-- intent-shift release notes and route-stickiness test results under `Documentacao/`
-
-### Detailed normative and implementation reference
-
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### Semantic route stickiness reference
-
-> Consolidated from `Documentacao/README_SEMANTIC_ROUTE_STICKINESS.md`.
-
-### Purpose
-
-This optional capability uses a lightweight LLM profile and no regex, phrase lists, or domain-specific language rules. It classifies each turn as:
-
-- `CONTINUE`: keep the active agent;
-- `ROUTE`: run the regular Enterprise Router;
-- `HUMAN_HANDOFF`: request human assistance;
-- `END_SESSION`: finish the automated session.
-
-The classifier does not answer the user, execute tools, or implement domain rules. Human handoff and session ending are handled by global graph nodes.
-
-### Flow
-
-```text
-Incoming turn
-  -> lightweight semantic classifier
-       CONTINUE + active agent -> active agent
-       ROUTE / low confidence / error -> Enterprise Router
-       HUMAN_HANDOFF -> human_handoff node
-       END_SESSION -> end_session node
-```
-
-`CONTINUE` is converted to `ROUTE` when there is no active agent. Global session actions can be detected on the first turn.
-
-### Configuration
-
-```dotenv
-ENABLE_ROUTE_STICKINESS=true
-ROUTE_STICKINESS_LLM_PROFILE=route_continuity
-ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
-ROUTE_STICKINESS_HISTORY_TURNS=2
-ROUTE_STICKINESS_MAX_TOKENS=80
-HUMAN_HANDOFF_MESSAGE=I will transfer your request to a person.
-END_SESSION_MESSAGE=The session has ended. Thank you for contacting us.
-```
-
-```yaml
-profiles:
-  route_continuity:
-    provider: oci_openai
-    model: openai.gpt-4.1-mini
-    temperature: 0
-    max_tokens: 80
-    timeout_seconds: 5
-```
-
-Use the smallest approved model available in the target OCI environment.
-
-### Human handoff contract
-
-The router returns route `human_handoff`, intent `human_handoff`, `handoff=true`, and metadata `session_control=HUMAN_HANDOFF`. The graph node sets:
-
-- `human_handoff_requested=true`;
-- `session_ended=false`;
-- `next_state=HUMAN_HANDOFF_REQUESTED`.
-
-It emits `session.human_handoff.requested`. The customer integration remains responsible for choosing the human queue and protocol.
-
-### End-session contract
-
-The router returns route `end_session`, intent `end_session`, and metadata `session_control=END_SESSION`. The graph node sets:
-
-- `session_ended=true`;
-- `human_handoff_requested=false`;
-- `next_state=SESSION_ENDED`.
-
-It emits `session.end.requested`. Channel-specific session expiration or connection closing remains an integration responsibility.
-
-### Safety behavior
-
-- Only decisions above the configured confidence threshold are accepted.
-- Invalid JSON, timeout, low confidence, or errors fall back to the Enterprise Router.
-- Human handoff and session ending do not execute domain agents or MCP tools.
-- The classifier never selects a human queue and never physically closes a channel connection.
+- libs/agent_framework/src/agent_framework/routing/continuity.py
+- libs/agent_framework/src/agent_framework/config/settings.py
+- templates/agent_template_backend/app/workflows/agent_graph.py
+- templates/agent_template_backend/app/state.py
+- templates/agent_template_backend/.env and .env.example
+- tests/unit/test_semantic_route_stickiness.py
 
 ### Tests
 
-Run:
+PYTHONPATH=libs/agent_framework/src pytest -q tests/unit/test_semantic_route_stickiness.py  
+The suite covers CONTINUE, ROUTE, low confidence, invalid output, HUMAN_HANDOFF, END_SESSION, global actions on the first turn, and CONTINUE without an active agent.
+
+### Limitations and integration
+
+- The classifier does not select the human queue.
+- The classifier does not close the SSE, HTTP, voice, or WhatsApp connection.
+- The global event must be consumed by the Channel Gateway or client integration.
+- The session-end node persists the result, but the concrete expiration policy is external.
+- Quality depends on the lightweight model and configured threshold.
+
+### Enterprise Router versus Supervisor
+
+> Content consolidated from `Documentacao/README_ROUTING_MODES.md`.
+
+This project supports two architectural designs for routing among agents without requiring two different frameworks.
+
+### Available modes
+
+Configure through an environment variable:
+
+```bash
+ROUTING_MODE=router
+```
+
+or:
+
+```bash
+ROUTING_MODE=supervisor
+```
+
+There is also the documentation key in `agent_template_backend/config/routing.yaml`:
+
+```yaml
+router:
+  mode: router
+```
+
+The `ROUTING_MODE` environment variable is the recommended way to activate a mode at runtime, especially in Docker, Kubernetes, or OCI.
+
+---
+
+### Option 1: Enterprise Router
+
+Flow:
+
+```text
+Usuário
+  -> Input Guardrails
+  -> EnterpriseRouter
+  -> AgentRegistry
+  -> 1 agente especialista
+  -> Output Guardrails
+  -> Judges
+  -> Supervisor Review
+  -> Persistência/eventos
+```
+
+Recommended when each message should be handled by a single specialist agent.
+
+Examples:
+
+- `Minha fatura veio alta` -> `billing_agent`
+- `Onde está meu pedido?` -> `orders_agent`
+- `Quero trocar um produto com defeito` -> `support_agent`
+
+Advantages:
+
+- Lower latency.
+- Lower token cost.
+- Simpler debugging.
+- Easier to operate in production.
+
+Limitation:
+
+- A message with multiple subjects must be routed to a primary agent or handled by handoff.
+
+---
+
+### Option 2: Supervisor
+
+Flow:
+
+```text
+Usuário
+  -> Input Guardrails
+  -> Supervisor.route_plan
+  -> supervisor_agent
+       -> billing_agent opcional
+       -> orders_agent opcional
+       -> product_agent opcional
+       -> support_agent opcional
+  -> Consolidação
+  -> Output Guardrails
+  -> Judges
+  -> Supervisor Review
+  -> Persistência/eventos
+```
+
+Recommended when a single message may involve several agents.
+
+Example:
+
+```text
+Meu pedido não chegou e também fui cobrado duas vezes.
+```
+
+In this case, the supervisor may activate:
+
+- `orders_agent`
+- `billing_agent`
+
+Advantages:
+
+- Supports multiple intents in the same message.
+- Allows response consolidation.
+- Facilitates enterprise scenarios with multiple domains.
+
+Costs:
+
+- Higher latency.
+- Higher token consumption.
+- Greater operational complexity.
+
+---
+
+### What changed in the code
+
+### 1. Configuration
+
+File:
+
+```text
+agent_framework/src/agent_framework/config/settings.py
+```
+
+The following configuration was added:
+
+```python
+ROUTING_MODE: Literal['router','supervisor'] = 'router'
+```
+
+### 2. LangGraph workflow
+
+File:
+
+```text
+agent_template_backend/app/workflows/agent_graph.py
+```
+
+The `enterprise_route` node was replaced by a generic node:
+
+```text
+routing_decision
+```
+
+This node decides the path based on `ROUTING_MODE`:
+
+- `router` uses `EnterpriseRouter`.
+- `supervisor` uses `Supervisor.route_plan`.
+
+The following node was also added:
+
+```text
+supervisor_agent
+```
+
+It executes one or more agents and consolidates the result.
+
+### 3. Supervisor
+
+File:
+
+```text
+agent_framework/src/agent_framework/supervisor/supervisor.py
+```
+
+The following structure was added:
+
+```python
+SupervisorPlan
+```
+
+And the method:
+
+```python
+route_plan(state)
+```
+
+This method returns a list of agents to execute.
+
+### 4. Debug
+
+Endpoint:
+
+```text
+POST /debug/route
+```
+
+It now respects `ROUTING_MODE` and allows you to quickly check how a message will be routed.
+
+---
+
+### How to test locally
+
+### Installation
+
+```bash
+cd agent_template_backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -U pip setuptools wheel
+pip install -e ../agent_framework
+pip install -r requirements.txt
+```
+
+### Router mode
+
+```bash
+export ROUTING_MODE=router
+uvicorn app.main:app --reload --port 8000
+```
+
+Test:
+
+```bash
+curl -X POST http://localhost:8000/debug/route \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"text":"Onde está meu pedido?","session_id":"s1"}}'
+```
+
+Expected result:
+
+```json
+{
+  "mode": "router",
+  "route": "orders_agent"
+}
+```
+
+### Supervisor mode
+
+```bash
+export ROUTING_MODE=supervisor
+uvicorn app.main:app --reload --port 8000
+```
+
+Test:
+
+```bash
+curl -X POST http://localhost:8000/debug/route \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"text":"Meu pedido atrasou e minha fatura veio duplicada","session_id":"s2"}}'
+```
+
+Expected result:
+
+```json
+{
+  "mode": "supervisor",
+  "route": "supervisor_agent",
+  "agents": ["billing_agent", "orders_agent"]
+}
+```
+
+---
+
+### Isolation
+
+The logical isolation key remains:
+
+```text
+tenant_id:agent_id:session_id
+```
+
+Use this key for memory, session, checkpoint, and telemetry. In production, standardize `agent_id` per specialist agent or per template, depending on the desired level of isolation.
+
+---
+
+### Recommendation
+
+Start production with:
+
+```bash
+ROUTING_MODE=router
+```
+
+Enable:
+
+```bash
+ROUTING_MODE=supervisor
+```
+
+when there is a real need for multiple agents in the same message.
+
+### Enterprise Routing and LLM fallback
+
+> Content consolidated from `Documentacao/README_ENTERPRISE_ROUTING.md`.
+
+This version includes the complete project with:
+
+- `agent_framework`: reusable framework.
+- `agent_template_backend`: FastAPI backend with LangGraph, OCI Generative AI, Langfuse, guardrails, judges, supervisor, and enterprise routing.
+- `agent_frontend`: independent web frontend.
+- `templates/template_telecom_billing_product`: example telecom template with Billing and Product agents.
+- `templates/template_retail_orders_support`: example e-commerce template with Orders and Support agents.
+
+### Enterprise routing
+
+Routing is located in:
+
+```text
+agent_framework/src/agent_framework/routing/
+```
+
+Main components:
+
+- `models.py`: `IntentDefinition`, `RouterStatePolicy`, and `RouteDecision` models.
+- `config_loader.py`: loads intents and policies from YAML.
+- `enterprise_router.py`: decides the destination agent by state, keyword, LLM, or fallback.
+
+The template uses:
+
+```text
+agent_template_backend/config/routing.yaml
+```
+
+### Decision order
+
+1. Conversational state (`state_policies`).
+2. Configurable keywords/intents.
+3. Optional LLM Router (`ENABLE_LLM_ROUTER=true`).
+4. Fallback (`router.fallback_agent`).
+
+### How to test routing without calling the final agent
+
+```bash
+curl -X POST http://localhost:8000/debug/route \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel": "web",
+    "payload": {
+      "text": "Minha fatura veio alta",
+      "user_id": "u1",
+      "channel_id": "browser-1",
+      "context": {"msisdn": "5511999999999"}
+    }
+  }'
+```
+
+Expected response:
+
+```json
+{
+  "route": "billing_agent",
+  "agent": "billing_agent",
+  "intent": "billing_invoice_explanation",
+  "method": "keyword"
+}
+```
+
+### How to enable LLM routing
+
+In the backend `.env`:
+
+```env
+LLM_PROVIDER=oci_openai
+OCI_GENAI_API_KEY=...
+OCI_GENAI_BASE_URL=https://inference.generativeai.sa-saopaulo-1.oci.oraclecloud.com/openai/v1
+OCI_GENAI_MODEL=openai.gpt-4.1
+ENABLE_LLM_ROUTER=true
+ROUTING_CONFIG_PATH=./config/routing.yaml
+```
+
+### How to add a new agent
+
+1. Create the agent class under `agent_template_backend/app/agents/`.
+2. Instantiate the agent in `AgentWorkflow.__init__`.
+3. Add the node in LangGraph.
+4. Add the route in `add_conditional_edges`.
+5. Create an intent in `config/routing.yaml` pointing to `agent: agent_name`.
+
+### Included templates
+
+### Template 1 — Telecom
+
+Directory:
+
+```text
+templates/template_telecom_billing_product
+```
+
+Agents:
+
+- BillingAgent
+- ProductAgent
+
+### Template 2 — Retail/E-commerce
+
+Directory:
+
+```text
+templates/template_retail_orders_support
+```
+
+Agents:
+
+- OrdersAgent
+- SupportAgent
+
+This second template shows how to reuse the same architecture for another business domain.
+
+### Generic deterministic intent shift — current behavior
+
+> Content consolidated from `Documentacao/RELEASE_NOTES_GENERIC_DETERMINISTIC_INTENT_SHIFT_V15.md`.
+
+### Problem fixed
+
+Route Stickiness could preserve the previous intent when the new message matched an intent configured in `routing.yaml`, but the user's phrasing omitted short connector words present in the configured keyword.
+
+Real configuration example:
+
+- keyword: `qual é o meu plano`
+- message: `qual o meu plano`
+
+The deterministic classification did not recognize the new intent, and continuity ended up preserving the previous intent.
+
+### Fix
+
+The `EnterpriseRouter` continues to use, in this order:
+
+1. exact match;
+2. complete token sequence with inserted words (`ordered_tokens`);
+3. informative-token sequence that tolerates omission of short connectors present in the keyword (`ordered_content_tokens`).
+
+The third strategy ignores, only on the keyword side, tokens of up to two characters and requires at least two informative tokens. There are no hardcoded intent names, agent names, domains, or business verbs.
+
+Thus, the solution is driven entirely by the intents loaded from the application's `routing.yaml`.
+
+### Precedence over Route Stickiness
+
+When the deterministic candidate found differs from the active intent, it preempts stickiness and returns:
+
+- `route_stickiness_preempted: true`
+- `previous_agent`
+- `previous_intent`
+- `keyword_match_strategy`
+
+The continuity LLM is not called on this path.
+
+### Covered cases
+
+### Same agent, new intent
+
+`retail_order_tracking` -> `quero cancelar meu pedido` -> `retail_order_cancel`
+
+### Same agent, different tools
+
+`contas_invoice_query` -> `qual o meu plano` -> `contas_plan_information`
+
+Even if both intents use `faturas_agent`, the tools change from `consultar_faturas` to `consultar_plano`.
+
+### Intent-shift precedence over stickiness
+
+> Content consolidated from `Documentacao/RELEASE_NOTES_ROUTE_STICKINESS_DETERMINISTIC_INTENT_SHIFT_V14.md`.
+
+### Problem fixed
+
+A multi-token keyword such as `cancelar pedido` was not recognized in phrases such as `quero cancelar meu pedido`. The legacy match used literal substring matching; therefore, the generic keyword `pedido` could preserve `retail_order_tracking`, and continuity reused the previous intent.
+
+### Fix
+
+The `EnterpriseRouter` now has a second deterministic stage for multi-token keywords: ordered-token matching with up to three intermediate tokens. No additional LLM call is made.
+
+Examples recognized by the configured keyword `cancelar pedido`:
+
+- `quero cancelar meu pedido`
+- `quero cancelar o meu pedido`
+- `pode cancelar esse pedido`
+- `gostaria de cancelar meu pedido`
+
+When this match identifies an intent different from the active one, it preempts route stickiness before the continuity LLM.
+
+Expected audit metadata:
+
+```json
+{
+  "method": "keyword",
+  "intent": "retail_order_cancel",
+  "metadata": {
+    "matched_keyword": "cancelar pedido",
+    "keyword_match_strategy": "ordered_tokens",
+    "route_stickiness_preempted": true,
+    "previous_intent": "retail_order_tracking"
+  }
+}
+```
+
+### LLM cost
+
+For an explicit change recognized deterministically, the continuity LLM classifier is not called. For messages with no explicit signal, Route Stickiness continues with the configured behavior.
+
+### Regression
+
+Tests cover the `retail_order_tracking -> retail_order_cancel` change within the same `orders_agent`, including intermediate words. The related suite passed 18 tests.
+
+### Shift from query to transactional action
+
+> Content consolidated from `Documentacao/RELEASE_NOTES_ROUTE_STICKINESS_TRANSACTION_SHIFT.md`.
+
+### Problem
+
+After `consultar pedido 123`, the message `Quero devolver o pedido 123` could remain on `orders_agent` because of route stickiness. Because the previous intent exposed only query tools, the runtime executed `consultar_pedido` again and the direct response repeated the order status.
+
+### Fixes
+
+- Explicit keywords configured in `routing.yaml` can preempt route stickiness when they point to another intent/agent.
+- `retail_support_exchange_return` now has a higher priority than `retail_order_tracking` for exchange/return messages.
+- Transactional tools declare `selection_keywords` in `tools.yaml`.
+- Direct read-only responses are blocked when the message contains a registered transactional action, even if the previous intent is still active.
+- Action-tool selection uses configuration, not domain-specific aliases hardcoded in the runtime.
+
+### Expected flow
+
+1. `consultar pedido 123` → `orders_agent` → `consultar_pedido` → direct response.
+2. `Quero devolver o pedido 123` → stickiness preemption → `support_agent` / `retail_support_exchange_return`.
+3. `consultar_pedido` validates the order.
+4. `solicitar_devolucao` is selected and, with mandatory confirmation, generates `AWAITING_CONFIRMATION`.
+5. `Sim, confirmo` executes the action tool exactly once.
+
+### Route-stickiness test coverage
+
+> Content consolidated from `Documentacao/TEST_RESULTS_ROUTE_STICKINESS.md`.
+
+Date: 2026-07-31
+
+### Command
 
 ```bash
 PYTHONPATH=libs/agent_framework/src pytest -q tests/unit/test_semantic_route_stickiness.py
 ```
 
-The suite covers CONTINUE, ROUTE, low confidence, invalid output, HUMAN_HANDOFF, END_SESSION, first-turn global actions, and CONTINUE without an active agent.
+### Result
 
-### Runtime routing responsibilities
-
-> Consolidated from `specs/SPEC-002-Agent-Runtime.md`.
-
-### Escopo
-
-O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
-
-### Componentes
-
-| Componente | Responsabilidade |
-|---|---|
-| Workflow Builder | Compila o grafo LangGraph. |
-| State Manager | Mantém o estado de execução. |
-| Session Manager | Resolve sessão e conversation_key. |
-| Memory Manager | Carrega e persiste histórico. |
-| Checkpoint Manager | Persiste estado LangGraph. |
-| Input Guardrail Node | Executa guardrails de entrada. |
-| Router Node | Decide rota/intent. |
-| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
-| Agent Node | Executa agente de domínio. |
-| MCP Client/Router | Executa tools por contrato. |
-| RAG Service | Recupera contexto documental. |
-| Output Supervisor | Revisa resposta antes de saída. |
-| Output Guardrail Node | Executa guardrails de saída. |
-| Judge Node | Avalia resposta. |
-| Persistence Node | Persiste mensagens, memória e checkpoint. |
-
-### State Model
-
-```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    context: dict
-    business_context: dict
-    tool_arguments: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    rag_metadata: dict
-    guardrails: list[dict]
-    judges: list[dict]
-    metadata: dict
-    errors: list[dict]
+```text
+9 passed
 ```
 
-### Workflow
+### Covered scenarios
 
-```mermaid
-flowchart TD
-    A[start] --> B[input_guardrails]
-    B --> C[routing_decision]
-    C --> D[agent_execution]
-    D --> E[output_supervisor]
-    E --> F[output_guardrails]
-    F --> G[judge]
-    G --> H[persist]
-    H --> I[end]
-    C --> J[handoff]
-    J --> C
+1. `CONTINUE` bypasses the Enterprise Router.
+2. `ROUTE` falls back to the Enterprise Router.
+3. Low-confidence `CONTINUE` falls back safely.
+4. Invalid model output falls back safely.
+5. With no active agent, the lightweight classifier can still detect global session actions.
+6. `HUMAN_HANDOFF` returns the global `human_handoff` route and session-control metadata.
+7. `END_SESSION` returns the global `end_session` route and session-control metadata.
+8. Global actions work on the first turn.
+9. `CONTINUE` without an active agent is normalized to `ROUTE`.
+
+### Additional validation
+
+```bash
+python -m compileall -q libs/agent_framework/src templates/agent_template_backend/app
 ```
 
-### Nós
+Compilation completed successfully.
 
-| Nó | Entrada | Saída |
-|---|---|---|
-| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
-| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
-| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
-| `output_supervisor` | `response_text` | `response_text` revisado |
-| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
-| `judge` | `response_text`, evidências | `judges` |
-| `persist` | `state` completo | checkpoint, memória, mensagens |
+### Source files
 
-### Router
+The files below were consolidated into this manual:
 
-```yaml
-routing:
-  mode: router
-  fallback_agent: billing_agent
-  enable_llm_router: false
-  intents:
-    billing_invoice_explanation:
-      route: billing_agent
-      keywords:
-        - fatura
-        - cobrança
-        - boleto
-      mcp_tools:
-        - consultar_fatura
-        - consultar_pagamentos
-```
+- `Documentacao/Manual de Roteamento Multi-Agent.docx`
+- `Documentacao/Route_Stickiness_Semantica_Agent_Framework_OCI.docx`
+- `Documentacao/README_ROUTING_MODES.md`
+- `Documentacao/README_ENTERPRISE_ROUTING.md`
+- `Documentacao/RELEASE_NOTES_GENERIC_DETERMINISTIC_INTENT_SHIFT_V15.md`
+- `Documentacao/RELEASE_NOTES_ROUTE_STICKINESS_DETERMINISTIC_INTENT_SHIFT_V14.md`
+- `Documentacao/RELEASE_NOTES_ROUTE_STICKINESS_TRANSACTION_SHIFT.md`
+- `Documentacao/TEST_RESULTS_ROUTE_STICKINESS.md`
 
-### Supervisor
+### Maintenance rule
 
-```yaml
-supervisor:
-  enabled: true
-  profile: supervisor
-  max_turns: 5
-  handoff_enabled: true
-  fallback_route: support_agent
-```
-
-### Memory
-
-| Provider | Uso |
-|---|---|
-| `memory` | Execução local e testes. |
-| `sqlite` | Desenvolvimento local persistente. |
-| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
-| `autonomous` | Produção com Oracle Autonomous Database. |
-
-### Checkpoints
-
-Checkpoint contém:
-
-```json
-{
-  "conversation_key": "default:telecom_contas:session-001",
-  "checkpoint_id": "ckpt-001",
-  "state": {},
-  "pending_writes": [],
-  "created_at": "2026-06-19T12:00:00Z"
-}
-```
-
-Formato entregue ao LangGraph:
-
-```python
-pending_writes: list[tuple[str, str, object]]
-```
-
-### Business Context
-
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
-
-### Ordem de Prioridade dos Dados
-
-1. `tool_arguments`
-2. `business_context`
-3. `context`
-4. `session.metadata`
-5. `state`
-6. extração complementar do texto
-
-### MCP Integration
-
-```mermaid
-flowchart LR
-    AgentNode --> ToolList[mcp_tools]
-    ToolList --> Mapping[mcp_parameter_mapping.yaml]
-    Mapping --> MCP[MCP Gateway/Router]
-    MCP --> Result[mcp_results]
-```
-
-### RAG Integration
-
-```yaml
-rag:
-  enabled: true
-  namespace_strategy: agent_id
-  top_k: 5
-  profile_generation: rag_generation
-```
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `runtime.started` | Execução iniciada. |
-| `runtime.session.loaded` | Sessão carregada. |
-| `runtime.memory.loaded` | Memória carregada. |
-| `runtime.checkpoint.loaded` | Checkpoint carregado. |
-| `runtime.route.selected` | Rota selecionada. |
-| `runtime.agent.started` | Agente iniciado. |
-| `runtime.agent.completed` | Agente concluído. |
-| `runtime.persist.completed` | Persistência concluída. |
-| `runtime.failed` | Falha controlada. |
-
-### Erros
-
-| Código | Condição | Tratamento |
-|---|---|---|
-| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
-| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
-| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
-| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
-| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
-| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
-
-
-
-### Contrato Durável de Estado Transacional
-
-Hosts que utilizam `AgentRuntime` com transações multi-turno DEVEM declarar no `AgentState` os campos `active_transaction` e `last_transaction`. O primeiro é a fonte canônica da transação em andamento e deve sobreviver a checkpoint/resume; o segundo mantém o snapshot da última transação terminal.
-
-```python
-active_transaction: dict[str, Any]
-last_transaction: dict[str, Any]
-```
-
-`selected_tool_call` e `pending_tool_call` são campos auxiliares/compatibilidade e não substituem o latch canônico. Durante `COLLECTING_PARAMETERS`, a retomada da transação e o consumo de parâmetros pendentes têm precedência sobre keyword routing genérico. Uma mudança de intenção só deve interromper a transação quando for inequívoca ou explicitamente solicitada pelo usuário.
-
-O contrato completo, ciclo de vida, precedência de roteamento, checklist e testes regressivos estão em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Runtime recebe GatewayRequest validado.
-- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
-- [ ] Input guardrails executam antes do roteamento.
-- [ ] Router ou Supervisor seleciona rota.
-- [ ] Agent Node executa sem acessar payload bruto de canal.
-- [ ] MCP é acessado por contrato.
-- [ ] RAG é acessado por serviço reutilizável.
-- [ ] Output guardrails executam antes da resposta final.
-- [ ] Judges geram JudgeResult.
-- [ ] Memória e checkpoint são persistidos conforme provider.
-- [ ] Hosts transacionais declaram `active_transaction` e `last_transaction` no `AgentState`.
-- [ ] Durante `COLLECTING_PARAMETERS`, respostas a parâmetros pendentes têm precedência sobre keyword routing genérico.
-- [ ] Erros geram NOC e resposta controlada.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Governance constraints affecting routing
-
-> Consolidated from `specs/SPEC-011-Governance-Model.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Governança é o conjunto de papéis, responsabilidades, controles, aprovações, evidências e processos que permite que a Agent Platform OCI seja usada por múltiplos times sem perder padronização, segurança, rastreabilidade e capacidade de evolução.
-
-A governança não substitui a engenharia. Ela define como a engenharia evolui de forma controlada.
-
-Em uma plataforma de agentes, governança cobre:
-
-- quem pode criar agentes;
-- quem pode alterar prompts;
-- quem pode liberar MCP tools;
-- quem aprova mudanças de guardrails;
-- quem aprova modelos;
-- quem aprova datasets;
-- quem promove para produção;
-- quais evidências são obrigatórias;
-- como auditar decisões da plataforma.
-
-### 2. Problema que resolve
-
-Sem governança, cada time tende a criar agentes de forma diferente.
-
-Problemas comuns:
-
-- prompts sem versionamento;
-- MCP tools sem owner;
-- datasets ausentes;
-- agentes sem avaliação;
-- produção sem certification;
-- mudanças de modelo sem rastreabilidade;
-- guardrails duplicados;
-- regras de negócio dentro do runtime;
-- uso diferente da plataforma por cada fornecedor;
-- dificuldade de manutenção.
-
-A governança cria um modelo único de adoção.
-
-### 3. Domínios de governança
-
-| Domínio | Escopo |
-| --- | --- |
-| Platform Governance | Framework, Runtime, Gateways, Evaluator, Certification Suite. |
-| Agent Governance | Agentes, prompts, regras de negócio, datasets e configs. |
-| Model Governance | LLM profiles, providers, fallback, custo e uso. |
-| MCP Governance | Tools, MCP servers, owners, SLAs, autorização e contratos. |
-| Data Governance | BusinessContext, RAG, datasets, memória e retenção. |
-| Security Governance | Identidade, autorização, secrets, auditoria e PII. |
-| Operational Governance | Deploy, monitoramento, alertas, SLOs e incidentes. |
-| Evaluation Governance | Judges, evaluator, certification e métricas. |
-
-
-### 4. Modelo de ownership
-
-### 4.1. Platform Team
-
-Responsável por:
-
-- Agent Framework;
-- Agent Runtime;
-- Agent Gateway;
-- Channel Gateway;
-- AI Gateway;
-- MCP Gateway;
-- Evaluator;
-- Certification Suite;
-- contratos canônicos;
-- documentação da plataforma;
-- templates oficiais.
-
-### 4.2. Domain Team
-
-Responsável por:
-
-- comportamento do agente;
-- prompts;
-- regras de negócio;
-- datasets;
-- configurações específicas;
-- validação funcional;
-- critérios de sucesso.
-
-### 4.3. Integration Team
-
-Responsável por:
-
-- MCP servers;
-- APIs externas;
-- SLAs de tools;
-- contratos de integração;
-- credenciais de backend;
-- disponibilidade de sistemas externos.
-
-### 4.4. SRE / DevOps
-
-Responsável por:
-
-- CI/CD;
-- deploy;
-- observabilidade;
-- alertas;
-- capacidade;
-- SLOs;
-- runbooks;
-- rollback.
-
-### 4.5. Security / Architecture
-
-Responsável por:
-
-- segurança;
-- arquitetura;
-- policies;
-- Workload Identity;
-- secrets;
-- revisão de risco;
-- aprovação de exceções.
-
-### 5. RACI
-
-| Atividade | Platform | Domain | Integration | SRE | Security |
-| --- | --- | --- | --- | --- | --- |
-| Framework change | R/A | C | I | C | C |
-| Runtime change | R/A | C | I | C | C |
-| New agent | C | R/A | C | I | I |
-| New MCP tool | C | C | R/A | I | C |
-| Prompt change | I | R/A | I | I | C |
-| Guardrail change | R | C | I | I | A |
-| Model profile change | R | C | I | I | C |
-| Production deploy | I | C | C | R/A | C |
-| Security review | I | C | C | C | R/A |
-| Certification | R/A | C | C | I | I |
-
-
-### 6. Governança de agentes
-
-Todo agente deve possuir:
-
-```yaml
-agent:
-  id: telecom_contas
-  owner: billing_team
-  technical_owner: ai_platform_team
-  business_objective: "Atendimento sobre faturas, pagamentos e cobranças"
-  status: active
-  version: 1.0.0
-```
-
-Artefatos obrigatórios:
-
-- `agents.yaml`;
-- `routing.yaml`;
-- `prompt_policy.yaml`;
-- `guardrails.yaml`;
-- `judges.yaml`;
-- `tools.yaml`;
-- `mcp_parameter_mapping.yaml`;
-- dataset de regressão;
-- testes;
-- evidências de evaluator;
-- evidências de certification.
-
-### 7. Governança de prompts
-
-Prompts devem ser versionados e rastreáveis.
-
-```yaml
-prompt:
-  name: billing_system_prompt
-  version: 1.3.0
-  owner: billing_team
-  reviewed_at: 2026-06-19
-  status: approved
-```
-
-Mudanças de prompt exigem:
-
-1. revisão do domain owner;
-2. execução de dataset;
-3. evaluator;
-4. comparação contra baseline;
-5. registro da versão.
-
-### 8. Governança de guardrails
-
-Guardrails globais pertencem à plataforma/segurança.
-
-Guardrails por agente pertencem ao domínio, mas precisam seguir o contrato da plataforma.
-
-```yaml
-guardrail:
-  code: REVPREC
-  version: 2.0.0
-  owner: platform_security
-  phase: output
-  mode: enforce
-```
-
-Mudanças em guardrails `enforce` exigem certification.
-
-### 9. Governança de judges
-
-Judges devem ter objetivo, métrica, threshold e owner.
-
-```yaml
-judge:
-  name: groundedness
-  version: 1.1.0
-  threshold: 0.70
-  owner: platform_quality
-```
-
-Mudanças de threshold exigem reexecução do evaluator.
-
-### 10. Governança de modelos
-
-Agentes não referenciam modelo diretamente.
-
-O modelo é resolvido por profile.
-
-```yaml
-profiles:
-  judge:
-    provider: oci_openai
-    model: openai.gpt-4.1
-    temperature: 0
-```
-
-Mudanças de modelo exigem:
-
-- validação de custo;
-- evaluator;
-- validação de qualidade;
-- validação de latência;
-- atualização de release notes.
-
-### 11. Governança de MCP
-
-Cada tool deve ter owner, SLA, timeout e contrato.
-
-```yaml
-tool:
-  name: consultar_fatura
-  version: 1.0.0
-  owner: billing_platform
-  sla: p95_2s
-  timeout_seconds: 30
-  idempotent: true
-```
-
-Tools mutáveis exigem política de confirmação.
-
-### 12. Governança de datasets
-
-Datasets são ativos de qualidade.
-
-```yaml
-dataset:
-  name: telecom_contas_regression
-  version: 1.0.0
-  owner: billing_team
-```
-
-Datasets devem conter:
-
-- entrada;
-- BusinessContext;
-- rota esperada;
-- tools esperadas;
-- critérios mínimos;
-- casos negativos;
-- casos de segurança.
-
-### 13. Processo de aprovação
-
-```mermaid
-flowchart LR
-    Dev[Development] --> Tests[Tests]
-    Tests --> Eval[Evaluator]
-    Eval --> Cert[Certification]
-    Cert --> Sec[Security Review]
-    Sec --> Arch[Architecture Approval]
-    Arch --> HML[Homologation]
-    HML --> PROD[Production]
-```
-
-### 14. Evidências obrigatórias
-
-- relatório de testes;
-- relatório evaluator;
-- relatório certification;
-- trace Langfuse;
-- logs e métricas;
-- checklist de segurança;
-- release notes;
-- versão dos artefatos.
-
-### 15. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Prompt sem owner | Dificulta manutenção e aprovação. | Definir owner no metadata. |
-| Tool sem SLA | Operação sem expectativa de resposta. | Registrar SLA em tools.yaml. |
-| Dataset ausente | Sem regressão objetiva. | Criar dataset mínimo. |
-| Guardrail hardcoded | Governança fora do YAML. | Mover para config. |
-| Modelo definido no agente | Quebra governança de modelos. | Usar AI Gateway profiles. |
-
-
-### 16. Critérios de aceite
-
-- [ ] Cada agente possui owner funcional e técnico.
-- [ ] Prompts estão versionados.
-- [ ] Tools MCP possuem owner, SLA e versão.
-- [ ] Guardrails possuem owner e modo.
-- [ ] Judges possuem threshold e versão.
-- [ ] Datasets estão versionados.
-- [ ] Evaluator roda por agente.
-- [ ] Certification aprova antes de produção.
-- [ ] Release possui evidências.
-- [ ] Exceções são documentadas.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/03_transaction_workflows_and_state.md b/docs/developer/en/03_transaction_workflows_and_state.md
index 528e65d..86a3cd9 100644
--- a/docs/developer/en/03_transaction_workflows_and_state.md
+++ b/docs/developer/en/03_transaction_workflows_and_state.md
@@ -1,124 +1,73 @@
-
 ### Transactional Workflows and State
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **transaction state, parameter collection, confirmation, pause/resume and execution evidence**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **transaction state, parameter collection, confirmation, pause/resume, and operational evidence**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Transaction state, parameter collection, confirmation, pause/resume and execution evidence.
+Transaction state, parameter collection, confirmation, pause/resume, and operational evidence.
 
 ### Consolidated technical content
 
-### Transaction Workflows, Multi-turn State and Resume
+### Transactional Workflows, Multi-turn State, and Resume
 
-This guide is the canonical developer reference for side-effecting multi-turn operations.
+Implementation guide for multi-step operations, canonical transaction-state source, confirmation, parameter merge, pause/resume, operational evidence, and routing interaction.
 
-### Why a deterministic transaction engine exists
+### How to use this document
 
-A general-purpose LLM is useful for language understanding and composition, but it should not own the sequence of critical side effects. The framework therefore supports an optional deterministic LangGraph workflow engine. Domain YAML/actions stay with the agent; the framework supplies reusable orchestration and state semantics. Legacy direct-tool execution remains available for agents that have not opted into workflows.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### Canonical transaction state
+### Multi-turn transaction-state guide
 
-The transaction object is the source of truth for the active operation. It should explicitly represent the current operation/tool/workflow, collected parameters, missing parameters, confirmation requirement/status, execution result/evidence and lifecycle status such as collecting, awaiting confirmation, executing, completed, failed or cancelled.
+> Content consolidated from `docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`.
 
-Checkpoint persistence is not a substitute for transaction state. A checkpoint may contain historical graph state; the runtime must still identify the canonical active transaction before resuming anything.
-
-### Parameter merge
-
-Parameter collection is incremental. Existing valid parameters remain in the transaction and newly extracted parameters are merged. The runtime must not discard previously collected values just because the latest message contains only one missing field.
-
-When the user supplies a value expected by the active transaction, that parameter is processed before generic intent-shift routing. This is essential for natural language such as a bare amount, date, invoice id or service name.
-
-### Confirmation
-
-A transactional policy may require explicit confirmation. The workflow enters an awaiting-confirmation state and must not invoke the side-effecting MCP tool until confirmation is accepted. Rejection cancels/abandons the operation according to the workflow policy. Unrelated messages may be evaluated for intent shift instead of being coerced into confirmation.
-
-### Pause and resume
-
-A paused workflow resumes from persisted state and the next valid node. Resume logic must verify the active transaction rather than reopening every historical transaction found in checkpoints. Closed/completed/cancelled transactions remain closed.
-
-### Operational evidence
-
-Logical `COMPLETED` state alone is not proof that the external action succeeded. The final state and response should be grounded in execution evidence such as MCP results, returned operation/protocol identifiers or an explicit successful tool result. The framework distinguishes intent to execute, attempted execution and confirmed success.
-
-### Framework versus agent ownership
-
-The framework owns generic lifecycle/state handling, confirmation plumbing, pause/resume mechanics and tool-policy integration. The agent owns the business workflow definition, parameter descriptions, domain validation and tool/action mapping.
-
-### Minimum regression matrix
-
-Test at least: one-parameter collection, multiple parameters across turns, multiple parameters in one sentence, confirmation accept/reject, unrelated message during confirmation, parameter value that resembles an intent, pause/resume, backend restart, completed transaction followed by a new request, explicit transaction interruption, MCP success, MCP error/timeout and no-evidence failure.
-
-### Common anti-patterns
-
-Do not derive active transaction from checkpoint existence alone. Do not reset the full parameter map on each turn. Do not let route stickiness consume a valid transaction parameter. Do not mark success before receiving external evidence. Do not hardcode domain parameter names in shared transaction code.
-
-### Source material consolidated
-
-- `docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`
-- `docs/ADR_TRANSACTIONAL_WORKFLOW_ENGINE.md`
-- `Documentacao/IMPLEMENTACAO_WORKFLOWS_TRANSACIONAIS.md`
-- `FIX_TRANSACTION_PARAMETER_PRECEDENCE.md`
-- `FIX_TRANSACTION_INTENT_LOOP.md`
-- `docs/TRANSACTION_OPERATIONAL_EVIDENCE_FIX.md`
-- `Documentacao/VALIDACAO_TRANSACIONAL_BACKEND_MCP.md`
-
-### Detailed normative and implementation reference
-
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### Full multi-turn transaction state developer guide
-
-> Consolidated from `docs/TRANSACTION_STATE_DEVELOPER_GUIDE_en.md`.
-
-This document defines the operational contract for multi-turn transactions in Agent Framework OCI. It is normative for hosts and templates that use `AgentRuntime`, LangGraph checkpoints, and transactional tools.
+This document defines the operational contract for multi-turn transactions in Agent Framework OCI. It is normative for hosts and templates that use `AgentRuntime`, LangGraph checkpointing, and transactional tools.
 
 ### 1. Goal
 
-A transaction may span multiple turns:
+A transaction can span several turns. Example:
 
 ```text
-User: cancel my order
-Framework: provide the order number
-User: PED-1001
-Framework: confirm cancellation?
-User: yes
-Framework: execute the tool
+Usuário: quero cancelar o pedido
+Framework: informe o número do pedido
+Usuário: PED-1001
+Framework: confirma o cancelamento?
+Usuário: sim
+Framework: executa a tool
 ```
 
-The framework must preserve the transaction across all turns without relying on LLM reclassification, keyword routing, or re-extraction of parameters already collected.
+The framework must preserve the transaction across all these turns without depending on LLM reclassification, keyword routing, or re-extraction of parameters that have already been obtained.
 
-### 2. Canonical transaction state
+### 2. Canonical transaction-state source
 
-The canonical in-flight transaction is `active_transaction`.
+The canonical state for the in-progress transaction is `active_transaction`.
 
 ```python
 active_transaction: dict[str, Any]
 last_transaction: dict[str, Any]
 ```
 
-Every `AgentState` used by a host that enables multi-turn transactions **MUST** declare both fields. LangGraph uses the state schema for checkpoint persistence, so a field created dynamically by the runtime alone is not a safe durable contract.
+Every `AgentState` used by a host that enables multi-turn transactions **MUST** declare both fields. Because LangGraph uses the state schema for persistence/checkpointing, a field created only dynamically by the runtime is not a safe durable contract.
 
-Minimal example:
+Minimum example:
 
 ```python
 from typing import Any, TypedDict
 
 class AgentState(TypedDict, total=False):
-    # ...normal fields...
+    # ...campos normais...
     selected_tool_call: dict[str, Any]
     pending_tool_call: dict[str, Any]
     active_transaction: dict[str, Any]
@@ -129,108 +78,172 @@ class AgentState(TypedDict, total=False):
     confirmation_received: bool
 ```
 
-### 3. Field responsibilities
+### 3. Role of each field
 
-| Field | Responsibility | Rule |
+| Field | Role | Rule |
 |---|---|---|
-| `active_transaction` | Canonical in-flight transaction | Must survive checkpoint/resume while active. |
-| `last_transaction` | Snapshot of the latest terminal transaction | Used for audit/evidence; does not automatically reactivate a transaction. |
-| `transaction_status` | Current logical status | E.g. `COLLECTING_PARAMETERS`, `AWAITING_CONFIRMATION`, `COMPLETED`, `CANCELLED`, `OUT_OF_SCOPE`. |
+| `active_transaction` | Canonical source of the active transaction | Must survive checkpoint/resume while the transaction is active. |
+| `last_transaction` | Snapshot of the last terminal transaction | Used for audit, evidence, and controlled continuity; it does not automatically reactivate the transaction. |
+| `transaction_status` | Current logical state | E.g. `COLLECTING_PARAMETERS`, `AWAITING_CONFIRMATION`, `COMPLETED`, `CANCELLED`, `OUT_OF_SCOPE`. |
 | `missing_parameters` | Parameters still required | Must reflect canonical transaction state, not only the current message. |
-| `selected_tool_call` | Auxiliary/backward-compatible state | Must not replace `active_transaction` as canonical state. |
-| `pending_tool_call` | Auxiliary/backward-compatible state | May support compatibility but is not the primary latch. |
-| `next_state` | Workflow routing guidance | Keeps the correct node/agent during collection/confirmation. |
-| `transaction_pre_validation` | Pre-validation evidence | Stores validation before confirmation/execution. |
-| `transaction_evidence` | Execution evidence | Stores results and the transaction execution trail. |
+| `selected_tool_call` | Auxiliary/compatibility state | Must not replace `active_transaction` as the canonical source. |
+| `pending_tool_call` | Auxiliary/compatibility state | May be used for compatibility, but not as the primary latch. |
+| `next_state` | Workflow routing guidance | Helps keep the correct node/agent during collection/confirmation. |
+| `transaction_pre_validation` | Pre-validation evidence | Preserves validation results before confirmation/execution. |
+| `transaction_evidence` | Execution evidence | Preserves transaction results and execution trail. |
 
 ### 4. Recommended lifecycle
 
 ```text
 IDLE
-  ↓ transactional intent
+  ↓ intenção transacional
 COLLECTING_PARAMETERS
-  ↓ complete parameters
-PRE_VALIDATION (when configured)
-  ↓ eligible
+  ↓ parâmetros completos
+PRE_VALIDATION (quando configurado)
+  ↓ elegível
 AWAITING_CONFIRMATION
-  ↓ positive confirmation
+  ↓ confirmação positiva
 EXECUTING
   ↓
 COMPLETED
 ```
 
-Alternative terminal outcomes include `CANCELLED`, `OUT_OF_SCOPE`, and `FAILED`.
+Alternative terminal outcomes:
+
+```text
+CANCELLED
+OUT_OF_SCOPE
+FAILED
+```
+
+The runtime may represent some phases internally without a separate public `transaction_status`. The requirement is to preserve the latch and not lose arguments already collected.
 
 ### 5. Incremental parameter merge
 
-A later answer must complement the existing transaction instead of rebuilding it from the latest text only.
+A later response must complement the existing transaction, never recreate it only from the current text.
 
 ```python
 existing = dict((state.get("active_transaction") or {}).get("arguments") or {})
-new_values = {"amount": "71.99"}
+new_values = {"valor": "71.99"}
 arguments = {**existing, **new_values}
 ```
 
-Previously collected arguments must remain available on subsequent turns.
+Expected example:
 
-### 6. Routing precedence during an active transaction
+```text
+Turno 1: subject = "TIM CTRL Redes Sociais 8.0"
+Turno 2: valor = "71.99"
+Resultado: subject + valor permanecem disponíveis
+```
 
-When `active_transaction` is in `COLLECTING_PARAMETERS`, the message must first be evaluated as a possible answer to pending parameters.
+### 6. Routing precedence during a transaction
+
+When an `active_transaction` exists in `COLLECTING_PARAMETERS`, the message must first be evaluated as a possible answer to the pending parameters.
 
 Normative precedence:
 
-1. clearly fills a pending parameter → continue transaction;
-2. explicit cancel/abandon → cancel transaction;
-3. unambiguous new intent → interrupt and route;
-4. generic keyword in the same domain/agent → **do not** interrupt;
-5. ambiguous message → keep transaction and clarify.
+1. pending parameter clearly filled → continue the transaction;
+2. explicit cancellation/abandonment → cancel the transaction;
+3. unequivocal new intent → interrupt the transaction and route;
+4. generic keyword from the same domain/agent → **do not** interrupt the transaction;
+5. ambiguous message → keep the transaction and clarify.
+
+Examples:
 
 | Current state | Message | Correct result |
 |---|---|---|
 | `retail_order_cancel`, missing `order_id` | `PED-1001` | Continue cancellation and fill `order_id`. |
-| `retail_order_cancel`, missing `order_id` | `the order is PED-1001` | Continue cancellation; `order` must not switch to tracking. |
-| contestation, missing `amount` | `R$ 71.99` | Continue contestation and fill amount. |
-| pending cancellation | `forget it, show my bill` | Explicit interruption is allowed. |
-| pending cancellation | `track my order` | Unambiguous shift to tracking is allowed. |
+| `retail_order_cancel`, missing `order_id` | `o pedido é o PED-1001` | Continue cancellation; `pedido` must not become tracking. |
+| dispute, missing `valor` | `R$ 71,99` | Continue dispute and fill `valor`. |
+| cancellation pending | `esquece, quero ver minha fatura` | Explicit interruption allowed. |
+| cancellation pending | `quero rastrear pedido` | Unequivocal shift to tracking allowed. |
 
 ### 7. Checkpoint and resume
 
-Before normal routing, restore the checkpoint with the same conversation identity (`tenant_id`, `agent_id`, `session_id`/`conversation_key` according to the host contract).
+Before running normal routing, the host must restore the checkpoint using the same conversation identity (`tenant_id`, `agent_id`, `session_id`/`conversation_key` according to the host contract).
 
-An active transaction must be resumed before generic keyword routing or LLM continuity. `COLLECTING_PARAMETERS` without `active_transaction` should be treated as inconsistent state and diagnosed rather than silently restarting the tool.
+After restoration:
 
-### 8. Framework vs. agent responsibility
+```text
+active_transaction existe
+       ↓
+status ativo?
+       ↓ sim
+retomar a transação antes de keyword routing / continuity LLM
+```
 
-Framework owns latch persistence, argument merge, collection/confirmation states, resume precedence, deterministic confirmation, idempotency/evidence, and checkpoint/resume.
+A `COLLECTING_PARAMETERS` state without `active_transaction` must be treated as a state inconsistency and observed/diagnosed; it must not silently restart the tool from the current message.
 
-The agent owns domain tools, required parameters, domain messages, domain eligibility/pre-validation, and customer-facing final responses. It must not create a parallel transaction engine.
+### 8. What belongs to the framework and what belongs to the agent
 
-### 9. New host/template checklist
+Framework:
+
+- latch persistence;
+- argument merge;
+- collection/confirmation states;
+- resume precedence;
+- deterministic confirmation;
+- idempotency and evidence;
+- checkpoint/resume.
+
+Agent:
+
+- domain-tool definitions;
+- required parameters and domain messages;
+- domain-specific eligibility rules;
+- domain-specific pre-validation, when applicable;
+- final customer response.
+
+The agent must not implement a second transactional engine in parallel with `AgentRuntime`.
+
+### 9. Checklist for new hosts/templates
 
 - [ ] `AgentState` declares `active_transaction`.
 - [ ] `AgentState` declares `last_transaction`.
-- [ ] `transaction_status` and `missing_parameters` are declared when used.
-- [ ] Checkpoint provider is compatible with the state schema.
-- [ ] The same conversation identity is reused across turns.
-- [ ] New parameters are merged with previously collected arguments.
-- [ ] Pending parameter answers take precedence over generic keyword routing.
-- [ ] Explicit intent shifts remain possible.
-- [ ] Transactional agent responses propagate `transaction_state_patch(state)` where required by the template.
-- [ ] Multi-turn tests cover collection, confirmation, interruption, and resume.
+- [ ] `transaction_status` and `missing_parameters` are part of state when used.
+- [ ] The host uses checkpointing compatible with the state schema.
+- [ ] The same `conversation_key` is used across turns of the same conversation.
+- [ ] Previously collected parameters are merged with new values.
+- [ ] Parameter answers take precedence over generic keyword routing.
+- [ ] Explicit intent changes remain possible.
+- [ ] The agent uses `transaction_state_patch(state)` when returning transactional responses if the template requires it.
+- [ ] Multi-turn tests exist for collection, confirmation, interruption, and resume.
 
 ### 10. Minimum regression tests
 
-Test order cancellation with a pending `order_id`, contestation with a subject collected on the first turn and amount on the second, explicit interruption to a different intent, and checkpoint/resume using the same conversation identity.
+```text
+A. cancelamento de pedido
+1. "quero cancelar pedido"
+2. "o pedido é o PED-1001"
+Esperado: continua retail_order_cancel; não vira retail_order_tracking.
+
+B. contestação
+1. "não contratei TIM CTRL Redes Sociais 8.0"
+2. "R$ 71,99"
+Esperado: subject e valor chegam juntos à pre-validation.
+
+C. interrupção explícita
+1. iniciar transação e deixar parâmetro pendente
+2. "esquece, quero ver minha fatura"
+Esperado: transação é interrompida e nova intenção é roteada.
+
+D. checkpoint/resume
+1. iniciar transação
+2. persistir/checkpoint
+3. reconstruir execução usando a mesma conversation_key
+4. fornecer o parâmetro faltante
+Esperado: active_transaction é restaurado e concluído sem reiniciar a tool.
+```
 
 ### 11. Anti-patterns
 
-- rebuilding the transaction from only the latest message;
+- rebuilding the transaction only from the last message;
 - using `selected_tool_call` as the only latch source;
-- removing `active_transaction` because it appears redundant;
-- allowing a generic keyword such as `order` to interrupt `order_id` collection;
-- keeping parameters only in node-local variables;
-- duplicating transaction confirmation in the agent prompt;
-- clearing the latch before a terminal state.
+- removing `active_transaction` from `AgentState` because it appears redundant;
+- allowing a generic keyword such as `pedido` to interrupt `order_id` collection;
+- storing parameters only in local node variables;
+- duplicating transactional confirmation in the agent prompt;
+- clearing the latch before terminal state.
 
 ### 12. Project references
 
@@ -243,588 +256,304 @@ Test order cancellation with a pending `order_id`, contestation with a subject c
 - `Tuning-Performance/Transaction_Pre_Validation/`
 - `Tuning-Performance/Transaction_Evidence/`
 
-### Runtime state and execution model
+### Transactional workflow engine architectural decision
 
-> Consolidated from `specs/SPEC-002-Agent-Runtime.md`.
+> Content consolidated from `docs/ADR_TRANSACTIONAL_WORKFLOW_ENGINE.md`.
 
-### Escopo
+### Decision
 
-O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
+Add an optional deterministic execution capability based on LangGraph to the framework. The engine is generic; YAML definitions and domain actions remain in the agents.
 
-### Componentes
+### Rationale
 
-| Componente | Responsabilidade |
-|---|---|
-| Workflow Builder | Compila o grafo LangGraph. |
-| State Manager | Mantém o estado de execução. |
-| Session Manager | Resolve sessão e conversation_key. |
-| Memory Manager | Carrega e persiste histórico. |
-| Checkpoint Manager | Persiste estado LangGraph. |
-| Input Guardrail Node | Executa guardrails de entrada. |
-| Router Node | Decide rota/intent. |
-| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
-| Agent Node | Executa agente de domínio. |
-| MCP Client/Router | Executa tools por contrato. |
-| RAG Service | Recupera contexto documental. |
-| Output Supervisor | Revisa resposta antes de saída. |
-| Output Guardrail Node | Executa guardrails de saída. |
-| Judge Node | Avalia resposta. |
-| Persistence Node | Persiste mensagens, memória e checkpoint. |
+Multi-step operations with side effects must not depend on the LLM to select the critical sequence. The solution reduces tokens, latency, and variability, while improving auditability, testing, and versioning.
 
-### State Model
+### Compatibility
 
-```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    context: dict
-    business_context: dict
-    tool_arguments: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    rag_metadata: dict
-    guardrails: list[dict]
-    judges: list[dict]
-    metadata: dict
-    errors: list[dict]
-```
+`execution.mode` defaults to `direct_tool`. Existing projects continue to use MCP directly. Workflow adoption is explicit per tool and may be controlled through `ENABLE_TRANSACTIONAL_WORKFLOWS`.
 
-### Workflow
+### Scope limits of this delivery
 
-```mermaid
-flowchart TD
-    A[start] --> B[input_guardrails]
-    B --> C[routing_decision]
-    C --> D[agent_execution]
-    D --> E[output_supervisor]
-    E --> F[output_guardrails]
-    F --> G[judge]
-    G --> H[persist]
-    H --> I[end]
-    C --> J[handoff]
-    J --> C
-```
+The foundation includes validation, file-based versioning, registry, sync/async execution, conditions, per-node retry, graph cache, and a policy adapter. Enterprise execution-record persistence, compensation/Saga, scope authorization, and workflow-specific IC/NOC emission must be connected to the abstractions available in each deployment before use in critical financial transactions.
 
-### Nós
+### Deterministic workflow implementation
 
-| Nó | Entrada | Saída |
-|---|---|---|
-| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
-| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
-| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
-| `output_supervisor` | `response_text` | `response_text` revisado |
-| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
-| `judge` | `response_text`, evidências | `judges` |
-| `persist` | `state` completo | checkpoint, memória, mensagens |
+> Content consolidated from `Documentacao/IMPLEMENTACAO_WORKFLOWS_TRANSACIONAIS.md`.
 
-### Router
+### Delivery
+
+An optional capability was added to `agent_framework_oci` to execute multi-step transactions as deterministic workflows compiled into LangGraph.
+
+### New module
+
+`libs/agent_framework/src/agent_framework/workflows/`
+
+- `models.py`: Pydantic contracts and structural validation;
+- `repository.py`: active-version resolution and immutable YAML reading;
+- `registry.py`: decoupled registration of sync/async actions;
+- `runtime.py`: StateGraph compilation, cache, and execution;
+- `tool_executor.py`: integration with tool policy;
+- `__init__.py`: public API.
+
+### Expanded policy
+
+`ToolPolicy` now accepts:
 
 ```yaml
-routing:
-  mode: router
-  fallback_agent: billing_agent
-  enable_llm_router: false
-  intents:
-    billing_invoice_explanation:
-      route: billing_agent
-      keywords:
-        - fatura
-        - cobrança
-        - boleto
-      mcp_tools:
-        - consultar_fatura
-        - consultar_pagamentos
+execution:
+  mode: direct_tool | workflow | agent
+  workflow: nome_do_workflow
+  version: active | 1
 ```
 
-### Supervisor
+The default remains `direct_tool`, preserving compatibility.
 
-```yaml
-supervisor:
-  enabled: true
-  profile: supervisor
-  max_turns: 5
-  handoff_enabled: true
-  fallback_route: support_agent
-```
+### Configuration
 
-### Memory
+The following were added:
 
-| Provider | Uso |
-|---|---|
-| `memory` | Execução local e testes. |
-| `sqlite` | Desenvolvimento local persistente. |
-| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
-| `autonomous` | Produção com Oracle Autonomous Database. |
+- `ENABLE_TRANSACTIONAL_WORKFLOWS=false`;
+- `WORKFLOWS_PATH=./workflows`.
 
-### Checkpoints
+### Template
 
-Checkpoint contém:
+Includes a complete order-return example with:
 
-```json
-{
-  "conversation_key": "default:telecom_contas:session-001",
-  "checkpoint_id": "ckpt-001",
-  "state": {},
-  "pending_writes": [],
-  "created_at": "2026-06-19T12:00:00Z"
-}
-```
+- confirmation and required fields from policy;
+- versioned workflow YAML;
+- domain actions in the backend;
+- deterministic branching based on validation result.
 
-Formato entregue ao LangGraph:
+### Validation performed
 
-```python
-pending_writes: list[tuple[str, str, object]]
-```
+- `tests/unit/test_tool_policies.py`: 4 tests passed;
+- Python compilation for framework, template, and new tests: passed;
+- the new LangGraph functional test was created but could not be run in this container because `langgraph` is not installed in the environment. The dependency is already declared in the framework `pyproject.toml`.
 
-### Business Context
+### Scope and safety
 
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
+This delivery creates the engine and policy integration. For critical production operations, it is still necessary to connect:
 
-### Ordem de Prioridade dos Dados
+- persistent execution store;
+- business idempotency in actions/APIs;
+- scope authorization;
+- workflow-specific IC/NOC telemetry;
+- compensation/Saga where applicable;
+- enterprise timeout and retry strategy.
 
-1. `tool_arguments`
-2. `business_context`
-3. `context`
-4. `session.metadata`
-5. `state`
-6. extração complementar do texto
+These items are explicitly documented to avoid the false impression that retry by itself guarantees transactional safety.
 
-### MCP Integration
+### Parameter-collection precedence
 
-```mermaid
-flowchart LR
-    AgentNode --> ToolList[mcp_tools]
-    ToolList --> Mapping[mcp_parameter_mapping.yaml]
-    Mapping --> MCP[MCP Gateway/Router]
-    MCP --> Result[mcp_results]
-```
+> Content consolidated from `FIX_TRANSACTION_PARAMETER_PRECEDENCE.md`.
 
-### RAG Integration
+This correction removes hardcoded textual extraction of transactional parameters and collects `policy.requires` through a generic LLM extractor.
 
-```yaml
-rag:
-  enabled: true
-  namespace_strategy: agent_id
-  top_k: 5
-  profile_generation: rag_generation
-```
+### Precedence rule
 
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `runtime.started` | Execução iniciada. |
-| `runtime.session.loaded` | Sessão carregada. |
-| `runtime.memory.loaded` | Memória carregada. |
-| `runtime.checkpoint.loaded` | Checkpoint carregado. |
-| `runtime.route.selected` | Rota selecionada. |
-| `runtime.agent.started` | Agente iniciado. |
-| `runtime.agent.completed` | Agente concluído. |
-| `runtime.persist.completed` | Persistência concluída. |
-| `runtime.failed` | Falha controlada. |
-
-### Erros
-
-| Código | Condição | Tratamento |
-|---|---|---|
-| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
-| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
-| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
-| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
-| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
-| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
-
-
-
-### Contrato Durável de Estado Transacional
-
-Hosts que utilizam `AgentRuntime` com transações multi-turno DEVEM declarar no `AgentState` os campos `active_transaction` e `last_transaction`. O primeiro é a fonte canônica da transação em andamento e deve sobreviver a checkpoint/resume; o segundo mantém o snapshot da última transação terminal.
-
-```python
-active_transaction: dict[str, Any]
-last_transaction: dict[str, Any]
-```
-
-`selected_tool_call` e `pending_tool_call` são campos auxiliares/compatibilidade e não substituem o latch canônico. Durante `COLLECTING_PARAMETERS`, a retomada da transação e o consumo de parâmetros pendentes têm precedência sobre keyword routing genérico. Uma mudança de intenção só deve interromper a transação quando for inequívoca ou explicitamente solicitada pelo usuário.
-
-O contrato completo, ciclo de vida, precedência de roteamento, checklist e testes regressivos estão em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Runtime recebe GatewayRequest validado.
-- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
-- [ ] Input guardrails executam antes do roteamento.
-- [ ] Router ou Supervisor seleciona rota.
-- [ ] Agent Node executa sem acessar payload bruto de canal.
-- [ ] MCP é acessado por contrato.
-- [ ] RAG é acessado por serviço reutilizável.
-- [ ] Output guardrails executam antes da resposta final.
-- [ ] Judges geram JudgeResult.
-- [ ] Memória e checkpoint são persistidos conforme provider.
-- [ ] Hosts transacionais declaram `active_transaction` e `last_transaction` no `AgentState`.
-- [ ] Durante `COLLECTING_PARAMETERS`, respostas a parâmetros pendentes têm precedência sobre keyword routing genérico.
-- [ ] Erros geram NOC e resposta controlada.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Canonical state contracts
-
-> Consolidated from `specs/SPEC-012-Canonical-Contracts.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Contratos canônicos são estruturas padronizadas usadas para desacoplar canais, gateways, runtime, agentes, tools, LLMs, evaluator e observabilidade.
-
-A plataforma usa contratos para garantir que componentes independentes possam evoluir sem quebrar uns aos outros.
-
-### 2. Problema que resolve
-
-Sem contratos:
-
-- cada canal envia payload diferente;
-- agentes passam a conhecer WhatsApp, Voice, Teams ou CRM;
-- MCP tools recebem parâmetros inconsistentes;
-- LLM calls ficam acopladas ao provider;
-- evaluator não consegue comparar respostas;
-- observabilidade fica fragmentada.
-
-Com contratos:
+While an active transaction exists, the framework handles the turn in this order:
 
 ```text
-Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
+ACTIVE_TRANSACTION
+       |
+       +-- COLLECTING_PARAMETERS
+       |      |
+       |      +-- LLM tenta extrair SOMENTE os parâmetros ainda pendentes
+       |      |
+       |      +-- extraiu >= 1 ?
+       |             |
+       |             +-- SIM -> continua a transação; NÃO avalia intent_shift
+       |             |
+       |             +-- NÃO -> libera EnterpriseRouter para avaliar intent_shift
+       |
+       +-- AWAITING_CONFIRMATION
+              |
+              +-- reconhece confirmação/rejeição explícita
+              |
+              +-- reconheceu ?
+                     |
+                     +-- SIM -> continua/cancela a transação; NÃO avalia intent_shift
+                     |
+                     +-- NÃO -> libera EnterpriseRouter para avaliar intent_shift
 ```
 
-### 3. Catálogo de contratos
+### TransactionParameterExtractor
 
-| Contrato | Uso |
-| --- | --- |
-| GatewayRequest | Entrada canônica da plataforma. |
-| ChannelResponse | Resposta canônica ao canal. |
-| BusinessContext | Identidade canônica de negócio. |
-| AgentState | Estado interno do runtime. |
-| Session | Sessão técnica/conversacional. |
-| Checkpoint | Persistência de estado LangGraph. |
-| ToolInvocation | Chamada canônica de tool MCP. |
-| ToolResult | Resposta canônica de tool MCP. |
-| LLMRequest | Chamada canônica ao AI Gateway. |
-| LLMResponse | Resposta canônica do AI Gateway. |
-| EvaluationRun | Execução do evaluator. |
-| EvaluationResult | Resultado de avaliação. |
-| CertificationResult | Resultado de certificação. |
-| EventEnvelope | Envelope de eventos IC/NOC/GRL. |
+New component:
 
+`libs/agent_framework/src/agent_framework/runtime/transaction_parameters.py`
 
-### 4. GatewayRequest
+Textual extraction of business parameters is performed exclusively by the LLM. The component receives:
 
-### 4.1. Uso
+- name of the active tool/transaction;
+- currently pending parameters;
+- already known arguments;
+- schema/types declared in `tools.yaml` when available;
+- tool description;
+- current user message.
 
-Usado por Channel Gateway e Agent Gateway para enviar mensagens ao Runtime.
+It does not know domain names such as `order_id`, `reason`, `subject`, `valor`, TIM, or retail. There is no regex for business entities.
 
-```json
-{
-  "channel": "web",
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "payload": {
-    "message": "Quero consultar minha fatura",
-    "session_id": "session-001",
-    "user_id": "user-001",
-    "message_id": "msg-001",
-    "business_context": {
-      "customer_key": "11999999999",
-      "contract_key": "3000131180",
-      "interaction_key": "301953872",
-      "session_key": "session-001"
-    },
-    "metadata": {
-      "request_id": "req-001",
-      "contract_version": "gateway-request-v1"
-    }
-  }
-}
-```
+The LLM can interpret, for example:
 
-### 4.2. Campos obrigatórios
+- `PED-1001` when only one compatible parameter is pending;
+- `o pedido é PED-1001`;
+- `PED-1001, desisti da compra`, filling two parameters in the same turn;
+- answers with the parameter name followed by the value;
+- answers containing only the value, when semantically unequivocal.
 
-- `channel`;
-- `payload.message`;
-- `payload.session_id`;
-- `payload.message_id`;
-- `tenant_id` quando multi-tenant;
-- `agent_id` quando não houver roteamento global.
+When in doubt, the prompt instructs the model to return `null`. A new request must not be transformed into a parameter value.
 
-### 5. ChannelResponse
+### Separation of responsibilities
 
-```json
-{
-  "channel": "web",
-  "session_id": "default:telecom_contas:session-001",
-  "text": "Resposta final do agente.",
-  "metadata": {
-    "tenant_id": "default",
-    "agent_id": "telecom_contas",
-    "route": "billing_agent",
-    "intent": "billing_invoice_explanation",
-    "guardrails": [],
-    "judges": []
-  }
-}
-```
+`tool_policies.yaml` remains the source of truth for `requires`.
 
-### 6. BusinessContext
+`tools.yaml` may provide types through `args_schema` and the tool description to improve interpretation without introducing domain-specific code.
 
-### 6.1. Uso
+`mcp_parameter_mapping.yaml` remains responsible for auxiliary parameters/MCP contract. Mapper strategies are explicitly excluded for fields present in `policy.requires`, so MCP extraction is not mixed with transactional collection.
 
-BusinessContext transporta identidade de negócio sem acoplar a plataforma ao formato de cada canal.
+The `EnterpriseRouter` uses the same LLM extractor only as a precedence *probe*. If at least one pending parameter is found, the turn remains in the transactional state. Extracted values are placed in decision metadata and reused by the runtime, avoiding a second LLM call in the same turn.
+
+### LLM profile
+
+The following was added to the templates:
 
 ```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
+transaction_parameter_extraction:
+  provider: oci_openai
+  model: openai.gpt-4.1-mini
+  temperature: 0
+  max_tokens: 500
+  timeout_seconds: 8
 ```
 
-### 6.2. Mapeamento para MCP
+Generation/component:
 
-```yaml
-tools:
-  consultar_fatura:
-    map:
-      customer_key: msisdn
-      contract_key: invoice_id
-      interaction_key: ura_call_id
-      session_key: session_id
+- `llm.transaction_parameter_extraction`
+- `transaction_parameter_extraction`
+
+### State cleanup
+
+On `intent_shift`, the abandoned transaction's `transaction_pre_validation` is removed so it does not contaminate the new transaction. The pre-validation result remains preserved while it belongs to its own transaction for audit purposes.
+
+### Tests added
+
+`tests/test_transaction_parameter_llm_precedence.py`
+
+Coverage:
+
+1. two parameters extracted in the same turn;
+2. one filled parameter takes precedence over a keyword that would indicate another intent;
+3. no parameter found releases `intent_shift`;
+4. absence of the old hardcoded `_extract_action_arguments()`;
+5. `sim` confirmation takes precedence over intent shift.
+
+### Transaction/intent loop fix
+
+> Content consolidated from `FIX_TRANSACTION_INTENT_LOOP.md`.
+
+Correction applied on 2026-08-20 to prevent a session from getting stuck in `COLLECTING_PARAMETERS` or `AWAITING_CONFIRMATION` when the user explicitly changes subject.
+
+### Corrected behavior
+
+Before:
+
+1. a transaction entered `COLLECTING_PARAMETERS`;
+2. `next_state` forced the same agent through `state_policies`;
+3. every following message was treated as an attempt to fill the missing parameter;
+4. a new intent such as `quais sao meus servicos` remained trapped in the previous flow.
+
+Now:
+
+- the `EnterpriseRouter` checks for an explicit intent change before applying the state lock;
+- explicit keyword has priority;
+- when necessary, the LLM router can detect a change with confidence >= `router.confidence_threshold`;
+- the decision receives `metadata.transaction_interruption=intent_shift`;
+- the runtime closes the pending transaction as `CANCELLED`, clears `next_state`, parameters, and latches, and proceeds with the new intent;
+- explicit cancellations such as `cancele essa operação anterior` also work during `COLLECTING_PARAMETERS`.
+
+### Tests added
+
+- intent change during `COLLECTING_PARAMETERS`;
+- short/low-confidence answer remains in the transaction;
+- explicit cancellation during parameter collection;
+- cleanup of transactional state before executing the new intent.
+
+Focused tests: 19 passed.
+
+### Operational execution evidence
+
+> Content consolidated from `docs/TRANSACTION_OPERATIONAL_EVIDENCE_FIX.md`.
+
+### Problem
+
+A confirmed transactional tool result was available only in the execution turn. On a later read-only turn, conversational memory could still mention the prior transaction (for example, a cancellation protocol), while the groundedness judge received only the current MCP results. This could classify a factually correct follow-up as unsupported.
+
+### Fix
+
+The framework now records completed/failed transactional tool outcomes as bounded operational evidence in LangGraph state/checkpoint (`transaction_evidence`). This is operational state, not Long Term Memory.
+
+For each new turn, the runtime correlates previous transaction evidence with the current resource using generic identifiers (`*_id`, `order_id`, `invoice_id`, `asset_id`, `resource_key`, etc.). Only relevant evidence is materialized as `relevant_transaction_evidence`.
+
+The same relevant evidence is:
+
+- injected into the answering LLM prompt;
+- merged with current MCP results for groundedness judges;
+- exposed in response metadata as `transaction_evidence` for diagnostics;
+- emitted with the completion telemetry event.
+
+The history is bounded to the 10 most recent transaction outcomes, and at most 5 correlated entries are injected for a turn.
+
+### Expected retail example
+
+1. `cancelar_pedido(PED-1001)` returns protocol `CANCEL-2026-001`.
+2. The result is persisted as transaction evidence.
+3. The next `consultar_pedido(PED-1001)` returns `EM_TRANSPORTE`.
+4. The answering agent and groundedness judge receive both the current order result and the prior cancellation evidence.
+5. A response that mentions `CANCEL-2026-001` is grounded rather than treated as an unsupported claim.
+
+### Integrated Backend/MCP validation
+
+> Content consolidated from `Documentacao/VALIDACAO_TRANSACIONAL_BACKEND_MCP.md`.
+
+### Implemented corrections
+
+- `mcp_tools` is treated as an allowlist, not as an automatic execution list.
+- `read_only` tools remain available for context enrichment.
+- Only one transactional tool compatible with the request is selected.
+- `require_confirmation: true` creates `pending_tool_call` and `AWAITING_CONFIRMATION`.
+- The confirmation turn executes the pending call with `confirmed: true`.
+- State exposes `selected_tool_call`, `tool_policy_result`, `confirmation_required`, `confirmation_received`, and `transaction_status`.
+- `reason` was standardized across catalog, mapping, and Retail FastMCP.
+- Orders `123` and `PED-ENTREGUE` return status `ENTREGUE` for positive tests.
+- The generic keyword `produto` was removed from the Telecom intent so it does not capture Retail returns.
+- `Normal` and `Route_Stickness` templates in `Tuning-Performance` were updated.
+
+### Recommended test
+
+1. `Quero devolver o pedido 123 porque me arrependi da compra.`
+2. Expected: `transaction_status=AWAITING_CONFIRMATION`, without executing `solicitar_devolucao`.
+3. `Sim, confirmo a devolução.`
+4. Expected: `transaction_status=COMPLETED` and a single execution of `solicitar_devolucao`.
+
+### Automated result
+
+```text
+7 passed
 ```
 
-### 7. AgentState
+### Source files
 
-```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    business_context: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    guardrails: list[dict]
-    judges: list[dict]
-```
+The files below were consolidated into this manual:
 
-### 8. ToolInvocation
+- `docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`
+- `docs/ADR_TRANSACTIONAL_WORKFLOW_ENGINE.md`
+- `Documentacao/IMPLEMENTACAO_WORKFLOWS_TRANSACIONAIS.md`
+- `FIX_TRANSACTION_PARAMETER_PRECEDENCE.md`
+- `FIX_TRANSACTION_INTENT_LOOP.md`
+- `docs/TRANSACTION_OPERATIONAL_EVIDENCE_FIX.md`
+- `Documentacao/VALIDACAO_TRANSACIONAL_BACKEND_MCP.md`
 
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "tool_name": "consultar_fatura",
-  "arguments": {
-    "msisdn": "11999999999",
-    "invoice_id": "3000131180"
-  },
-  "business_context": {
-    "customer_key": "11999999999",
-    "contract_key": "3000131180"
-  },
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
-```
+### Maintenance rule
 
-### 9. ToolResult
-
-```json
-{
-  "tool_name": "consultar_fatura",
-  "ok": true,
-  "data": {
-    "invoice_id": "3000131180",
-    "valor_total": 249.90,
-    "status": "ABERTA"
-  },
-  "cache": {
-    "hit": false,
-    "ttl_seconds": 300
-  },
-  "latency_ms": 140
-}
-```
-
-### 10. LLMRequest
-
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "profile": "judge",
-  "operation": "judge.response_quality",
-  "messages": [
-    {"role": "system", "content": "Você é um avaliador."},
-    {"role": "user", "content": "Avalie a resposta."}
-  ],
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
-```
-
-### 11. LLMResponse
-
-```json
-{
-  "provider": "oci_openai",
-  "model": "openai.gpt-4.1",
-  "profile": "judge",
-  "content": "Resultado",
-  "usage": {
-    "input_tokens": 1200,
-    "output_tokens": 300,
-    "total_tokens": 1500
-  },
-  "latency_ms": 820
-}
-```
-
-### 12. EvaluationRun
-
-```json
-{
-  "run_id": "eval-001",
-  "agent_id": "telecom_contas",
-  "source": "langfuse",
-  "period_start": "2026-06-18T00:00:00Z",
-  "period_end": "2026-06-19T00:00:00Z",
-  "status": "running"
-}
-```
-
-### 13. EventEnvelope
-
-```json
-{
-  "event_type": "IC.AGENT_COMPLETED",
-  "timestamp": "2026-06-19T12:00:00Z",
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "session_id": "session-001",
-  "trace_id": "trace-001",
-  "payload": {}
-}
-```
-
-### 14. Regras de evolução
-
-- campos novos devem ser opcionais;
-- campos obrigatórios não podem ser removidos dentro da mesma major;
-- mudança semântica exige nova versão;
-- contratos são versionados independentemente.
-
-### 15. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Payload bruto no Runtime | Acopla canais ao core. | Usar GatewayRequest. |
-| Tool recebendo BusinessContext bruto sem mapping | Quebra contrato da tool. | Usar mcp_parameter_mapping.yaml. |
-| LLM direto no agente | Quebra AI Gateway. | Usar LLMRequest/profile. |
-| Campos sem versão | Dificulta migração. | Declarar contract_version. |
-
-
-### 16. Critérios de aceite
-
-- [ ] GatewayRequest documentado e versionado.
-- [ ] ChannelResponse documentado e versionado.
-- [ ] BusinessContext usado por canais e MCP.
-- [ ] ToolInvocation e ToolResult padronizados.
-- [ ] LLMRequest e LLMResponse padronizados.
-- [ ] EvaluationRun e EvaluationResult padronizados.
-- [ ] EventEnvelope usado para IC/NOC/GRL.
-- [ ] Contratos possuem regras de evolução.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/04_mcp_integration_tools_and_policies.md b/docs/developer/en/04_mcp_integration_tools_and_policies.md
index 6cfed71..146418f 100644
--- a/docs/developer/en/04_mcp_integration_tools_and_policies.md
+++ b/docs/developer/en/04_mcp_integration_tools_and_policies.md
@@ -1,54 +1,323 @@
-
-### MCP, Tools, Policies and Parameter Extraction
+### MCP, Tools, Policies, and Parameter Extraction
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **tools, MCP Servers, mappings, read-only/transactional policies and parameter extraction**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **tools, MCP Servers, mappings, read-only/transactional policies, and parameter extraction**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Tools, mcp servers, mappings, read-only/transactional policies and parameter extraction.
+Tools, MCP servers, mappings, read-only/transactional policies, and parameter extraction.
 
 ### Consolidated technical content
 
-### MCP Integration, Tools, Policies and Parameter Extraction
+### MCP Integration, Tools, Policies, and Parameter Extraction
 
-This guide explains how agents consume business capabilities through MCP without embedding service logic in the framework.
+Development manual for integrating MCP Servers, registering tools, isolating tools by agent, configuring read-only/transactional policies, confirmation, and contextual parameter extraction.
 
-### MCP role
+### How to use this document
 
-MCP is the integration boundary for tools. The framework/runtime selects and prepares a tool call; the MCP layer connects that logical tool to a service. Business authorization, atomicity and backend transaction guarantees remain responsibilities of the MCP Server/service implementation.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### Registering an MCP Server
+### Complete MCP Server integration manual
 
-For local execution, register the server in the backend/gateway MCP configuration with its transport, endpoint, enabled flag and description. Docker/Kubernetes configurations should use the service DNS name rather than localhost.
+> Content consolidated from `Documentacao/Manual_Integracao_MCP_Servers_Agent_Framework.docx`.
 
-```yaml
+MCP Server Integration Manual  
+Multi-Agent Framework - Router, Supervisor, Tools, and External Servers  
+This document explains MCP concepts, how the current project integrates MCP servers, how to start the example Telecom and Retail servers, how to configure tools per agent, and how to evolve the implementation toward a solution that more closely follows the official MCP standard. The goal is to serve as a development, local-operations, and container/OCI deployment guide.
+
+### MCP concepts
+
+MCP stands for Model Context Protocol. It defines a standardized way for AI applications to access external context, tools, and capabilities from systems outside the model. Instead of putting integrations directly into the prompt or agent, MCP separates responsibilities: the agent decides what it needs, and an MCP server exposes tools, resources, and prompts in a controlled way.  
+In the official standard, MCP uses JSON-RPC messages and defines transports such as stdio and Streamable HTTP. The current project uses a simplified HTTP implementation to make understanding and local testing easier, with REST endpoints `/mcp/tools/list` and `/mcp/tools/call`. This is appropriate for tutorials and prototyping, but it can later evolve to an official MCP client.
+
+### How the current project organizes MCP
+
+The relevant project structure is:
+```
+projeto_multi_agent_isolado/
+  agent_framework/
+    src/agent_framework/mcp/
+      client.py
+      models.py
+      registry.py
+      tool_router.py
+
+  agent_template_backend/
+    config/
+      mcp_servers.yaml
+      mcp_servers.docker.yaml
+      tools.yaml
+      mcp_parameter_mapping.yaml
+    app/
+      main.py
+      workflows/agent_graph.py
+
+  mcp_servers/
+    telecom_mcp_server/
+      main.py
+      requirements.txt
+      Dockerfile
+    retail_mcp_server/
+      main.py
+      requirements.txt
+      Dockerfile
+
+  scripts/
+    run_mcp_servers.sh
+  docker-compose.yml
+```
+
+### Main components
+
+
+### Simplified HTTP contract used by the project
+
+```
+GET  /mcp/tools/list
+POST /mcp/tools/call
+
+Payload de chamada:
+{
+  "tool_name": "consultar_fatura",
+  "arguments": {
+    "msisdn": "11999999999",
+    "invoice_id": "INV-001"
+  }
+}
+
+Resposta esperada:
+{
+  "ok": true,
+  "result": { ... },
+  "metadata": {
+    "server": "telecom",
+    "tool": "consultar_fatura"
+  }
+}
+```
+
+### How to start the example MCP servers
+
+The project includes two example MCP servers: Telecom and Retail. They are independent FastAPI apps. The Telecom server runs on port 8100 and exposes tools such as `consultar_fatura`, `consultar_pagamentos`, `consultar_plano`, and `listar_servicos`. The Retail server runs on port 8200 and exposes tools such as `consultar_pedido`, `consultar_entrega`, `solicitar_troca`, and `solicitar_devolucao`.
+
+### Local startup through the script
+
+```
+cd projeto_multi_agent_isolado
+bash ./scripts/run_mcp_servers.sh
+```
+The script creates a venv in the root directory, installs the MCP-server dependencies, and starts both uvicorn processes in the background:
+```
+Telecom MCP: http://localhost:8100
+Retail MCP:  http://localhost:8200
+```
+
+### Manual startup of Telecom MCP
+
+```
+cd projeto_multi_agent_isolado
+python -m venv .venv
+source .venv/bin/activate
+pip install -r mcp_servers/telecom_mcp_server/requirements.txt
+uvicorn --app-dir mcp_servers/telecom_mcp_server main:app --host 0.0.0.0 --port 8100
+```
+
+### Manual startup of Retail MCP
+
+```
+cd projeto_multi_agent_isolado
+source .venv/bin/activate
+pip install -r mcp_servers/retail_mcp_server/requirements.txt
+uvicorn --app-dir mcp_servers/retail_mcp_server main:app --host 0.0.0.0 --port 8200
+```
+
+### Startup with Docker Compose
+
+```
+cd projeto_multi_agent_isolado
+docker compose up --build
+```
+In Docker Compose, the backend uses `mcp_servers.docker.yaml` because, inside the compose network, localhost would point to the backend container itself. Therefore the endpoints use service names: `telecom-mcp` and `retail-mcp`.
+```
+services:
+  telecom-mcp:
+    ports:
+      - "8100:8100"
+
+  retail-mcp:
+    ports:
+      - "8200:8200"
+
+  backend:
+    environment:
+      MCP_SERVERS_CONFIG_PATH: /app/config/mcp_servers.docker.yaml
+    depends_on:
+      - telecom-mcp
+      - retail-mcp
+```
+
+### How to test MCP tools
+
+
+### Direct health checks on the servers
+
+```
+curl http://localhost:8100/health
+curl http://localhost:8200/health
+```
+
+### List tools directly from Telecom MCP
+
+```
+curl http://localhost:8100/mcp/tools/list
+```
+
+### Call a tool directly on Telecom MCP
+
+```
+curl -X POST http://localhost:8100/mcp/tools/call   -H 'Content-Type: application/json'   -d '{
+    "tool_name": "consultar_fatura",
+    "arguments": {
+      "msisdn": "11999999999",
+      "invoice_id": "INV-001"
+    }
+  }'
+```
+
+### Call a tool directly on Retail MCP
+
+```
+curl -X POST http://localhost:8200/mcp/tools/call   -H 'Content-Type: application/json'   -d '{
+    "tool_name": "consultar_pedido",
+    "arguments": {
+      "order_id": "PED-1001",
+      "customer_id": "C-001"
+    }
+  }'
+```
+
+### Test through the agent backend
+
+After starting the MCP servers and backend, the backend provides debug endpoints to list and call tools through `MCPToolRouter`.
+```
+cd agent_template_backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ../agent_framework
+pip install -r requirements.txt
+uvicorn app.main:app --reload --reload-dir app --reload-dir config --port 8000
+curl http://localhost:8000/debug/mcp/tools
+
+curl -X POST http://localhost:8000/debug/mcp/call/consultar_fatura   -H 'Content-Type: application/json'   -d '{"msisdn":"11999999999","invoice_id":"INV-001"}'
+```
+
+### How the agent calls MCP in the flow
+
+The agent does not need to know the server URL. It calls a logical tool through `MCPToolRouter`. The expected flow is:
+```
+Usuário
+  -> FastAPI /gateway/message
+  -> Guardrails de input
+  -> Router ou Supervisor escolhe o agente
+  -> LangGraph executa o agent graph
+  -> Agent decide usar uma tool
+  -> MCPToolRouter.call("consultar_fatura", {...})
+  -> MCPRegistry resolve servidor telecom
+  -> MCPHttpClient chama http://localhost:8100/mcp/tools/call
+  -> Resultado volta ao agent graph
+  -> Guardrails de output
+  -> Judges
+  -> Resposta final
+```
+
+### Conceptual Python example
+
+```
+result = await tool_router.call(
+    "consultar_fatura",
+    {
+        "msisdn": context.get("msisdn"),
+        "invoice_id": context.get("invoice_id"),
+    },
+)
+
+if result.ok:
+    dados_fatura = result.result
+else:
+    # fallback controlado, telemetria e resposta segura
+    erro = result.error
+```
+
+### Example through a gateway message
+
+```
+curl -X POST http://localhost:8000/gateway/message   -H 'Content-Type: application/json'   -d '{
+    "channel": "web",
+    "payload": {
+      "session_id": "sess-tel-1",
+      "message": "Minha fatura veio alta",
+      "context": {
+        "msisdn": "11999999999",
+        "invoice_id": "INV-001"
+      }
+    }
+  }'
+curl -X POST http://localhost:8000/gateway/message   -H 'Content-Type: application/json'   -d '{
+    "channel": "web",
+    "payload": {
+      "session_id": "sess-ret-1",
+      "message": "Meu pedido não chegou",
+      "context": {
+        "order_id": "PED-1001",
+        "customer_id": "C-001"
+      }
+    }
+  }'
+```
+
+### How to configure new servers and tools
+
+
+### Add a new MCP Server
+
+Edit `agent_template_backend/config/mcp_servers.yaml` for local execution:
+```
 servers:
   crm:
     transport: http
     endpoint: http://localhost:8300/mcp
     enabled: true
-    description: CRM MCP Server
+    description: MCP Server de CRM.
+```
+Edit `agent_template_backend/config/mcp_servers.docker.yaml` for Docker execution:
+```
+servers:
+  crm:
+    transport: http
+    endpoint: http://crm-mcp:8300/mcp
+    enabled: true
+    description: MCP Server de CRM via docker-compose.
 ```
 
-### Registering a tool
+### Register a new tool
 
-```yaml
+Edit `agent_template_backend/config/tools.yaml`:
+```
 tools:
   consultar_cliente:
-    description: Query summarized customer data.
+    description: Consulta dados cadastrais resumidos do cliente.
     mcp_server: crm
     enabled: true
     args_schema:
@@ -56,58 +325,490 @@ tools:
       document_id: string
 ```
 
-The tool description and parameter descriptions are part of runtime behavior. They should be precise enough for semantic selection/extraction and must not be hidden in Python hardcodes.
+### Implement the endpoint in the MCP server
 
-### Tool isolation per agent
+```
+TOOLS = {
+    "consultar_cliente": {
+        "description": "Consulta dados cadastrais resumidos do cliente.",
+        "input_schema": {
+            "customer_id": "string",
+            "document_id": "string"
+        },
+    },
+}
 
-Every agent should see only the tools it needs. Use an allowlist or agent-specific `tools.yaml`. This reduces prompt ambiguity and limits operational risk.
+@app.post("/mcp/tools/call")
+async def call_tool(call: ToolCall):
+    if call.tool_name == "consultar_cliente":
+        return {
+            "ok": True,
+            "result": {
+                "customer_id": call.arguments.get("customer_id"),
+                "status": "ATIVO",
+                "segmento": "PREMIUM"
+            },
+            "metadata": {"server": "crm", "tool": "consultar_cliente"}
+        }
+```
 
-### Read-only versus transactional policies
+### How to isolate MCP by agent
 
-Policy configuration is optional and lives with the deployable agent, not inside the shared library. A default may treat tools as read-only, while individual tools declare `operation_type: transactional`, `require_confirmation: true` and required parameters.
+In a multi-agent architecture, not every agent should see every tool. The orders agent may use `consultar_pedido` and `consultar_entrega`. The billing agent may use `consultar_fatura` and `consultar_pagamentos`. This isolation reduces operational risk, improves governance, and simplifies each agent's prompt.
+
+### Simple option: allowlist per agent
+
+```
+agents:
+  - agent_id: billing_agent
+    allowed_tools:
+      - consultar_fatura
+      - consultar_pagamentos
+      - consultar_plano
+      - listar_servicos
+
+  - agent_id: orders_agent
+    allowed_tools:
+      - consultar_pedido
+      - consultar_entrega
+      - solicitar_troca
+      - solicitar_devolucao
+```
+
+### Recommended option: tools by configuration file
+
+For large projects, each agent can have its own `tools.yaml`, `guardrails.yaml`, and `judges.yaml`. This maintains real isolation by agent and makes versioning easier.
+```
+config/agents/telecom_contas/
+  prompt_policy.yaml
+  guardrails.yaml
+  judges.yaml
+  tools.yaml
+
+config/agents/retail_orders/
+  prompt_policy.yaml
+  guardrails.yaml
+  judges.yaml
+  tools.yaml
+```
+
+### How to deploy with Docker and OCI
+
+
+### Local deployment with Docker Compose
+
+The current `docker-compose.yml` already has separate services for `telecom-mcp`, `retail-mcp`, backend, and frontend. This separation is correct because MCP Servers should be independently scalable and versionable from the agent backend.
+```
+docker compose up --build
+
+# URLs externas para teste local:
+http://localhost:8100/health
+http://localhost:8200/health
+http://localhost:8000/debug/mcp/tools
+http://localhost:5173
+```
+
+### Deployment on OCI/OKE
+
+In Kubernetes/OKE, each MCP Server should be deployed as a Deployment + Service. The agent backend points to the Service's internal DNS. Conceptual example:
+```
+apiVersion: v1
+kind: Service
+metadata:
+  name: telecom-mcp
+spec:
+  selector:
+    app: telecom-mcp
+  ports:
+    - port: 8100
+      targetPort: 8100
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: telecom-mcp
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: telecom-mcp
+  template:
+    metadata:
+      labels:
+        app: telecom-mcp
+    spec:
+      containers:
+        - name: telecom-mcp
+          image: <registry>/telecom-mcp:1.0.0
+          ports:
+            - containerPort: 8100
+```
+
+### Backend configuration in Kubernetes
+
+```
+servers:
+  telecom:
+    transport: http
+    endpoint: http://telecom-mcp.default.svc.cluster.local:8100/mcp
+    enabled: true
+
+  retail:
+    transport: http
+    endpoint: http://retail-mcp.default.svc.cluster.local:8200/mcp
+    enabled: true
+```
+
+### Security, guardrails, and observability
+
+MCP greatly increases agent capability, but also increases the attack and operational-risk surface. A tool can query sensitive data, open protocols/cases, cancel services, generate credits, or execute business actions. Therefore, the integration must be protected before, during, and after the call.
+
+### Minimum security checklist
+
+- Every tool must have a clear description and argument schema.
+- Every action tool must require explicit user confirmation before execution.
+- Each agent must have a tool allowlist.
+- Sensitive data returned by MCP must pass through masking/sanitization before the final response.
+- Every MCP call must generate a trace/span/event in Langfuse or OpenTelemetry.
+- Timeouts and retry limits must be configured per tool or per server.
+- Do not expose MCP Servers directly to the internet without authentication, TLS, and network controls.
+- Separate read-only tools from transactional tools.
+
+### Recommended telemetry
+
+```
+span: mcp.tool_call
+attributes:
+  tenant_id
+  agent_id
+  session_id
+  tool_name
+  mcp_server
+  latency_ms
+  ok
+  error
+  input_argument_keys
+  result_size
+
+event: mcp.tool_call.completed
+metadata:
+  tool_name
+  server
+  ok
+  error
+```
+
+### Evolution toward official MCP
+
+The current project uses a simplified HTTP contract. For enterprise production there are two options. The first is to keep this internal contract for simplicity, provided it is well documented, secure, and versioned. The second is to evolve to an official MCP client/server with JSON-RPC, stdio, or Streamable HTTP.
+
+### Complete developer step-by-step
+
+```
+# 1. Baixar e abrir o projeto
+cd projeto_multi_agent_isolado
+
+# 2. Subir servidores MCP de exemplo
+bash ./scripts/run_mcp_servers.sh
+
+# 3. Em outro terminal, subir backend
+cd agent_template_backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ../agent_framework
+pip install -r requirements.txt
+uvicorn app.main:app --reload --reload-dir app --reload-dir config --port 8000
+
+# 4. Validar tools carregadas pelo backend
+curl http://localhost:8000/debug/mcp/tools
+
+# 5. Chamar tool Telecom
+curl -X POST http://localhost:8000/debug/mcp/call/consultar_fatura   -H 'Content-Type: application/json'   -d '{"msisdn":"11999999999","invoice_id":"INV-001"}'
+
+# 6. Chamar tool Retail
+curl -X POST http://localhost:8000/debug/mcp/call/consultar_pedido   -H 'Content-Type: application/json'   -d '{"order_id":"PED-1001","customer_id":"C-001"}'
+
+# 7. Testar pelo gateway conversacional
+curl -X POST http://localhost:8000/gateway/message   -H 'Content-Type: application/json'   -d '{"channel":"web","payload":{"session_id":"sess-ret-1","message":"Meu pedido não chegou","context":{"order_id":"PED-1001","customer_id":"C-001"}}}'
+```
+
+### Troubleshooting
+
+
+### References
+
+- Model Context Protocol Specification: https://modelcontextprotocol.io/specification
+- MCP Transports: https://modelcontextprotocol.io/specification/2025-11-25/basic/transports
+- MCP Resources: https://modelcontextprotocol.io/specification/2025-06-18/server/resources
+- Reference MCP Servers: https://github.com/modelcontextprotocol/servers
+- LangChain MCP Adapters: https://docs.langchain.com/oss/python/langchain/mcp
+- Project files: `agent_framework/src/agent_framework/mcp/*`, `agent_template_backend/config/mcp_servers.yaml`, `agent_template_backend/config/tools.yaml`, `mcp_servers/*`
+
+### Read-only and transactional policies
+
+The framework applies a minimal conversational policy immediately before the MCP call. `read_only` classification identifies queries; `transactional` identifies operations that change state. Authorization, idempotency, validation, and atomicity remain the responsibility of the MCP Server.
+
+### Backend configuration
+
+The configuration is optional and lives in `config/tool_policies.yaml` in `agent_template_backend`. The path can be set through `TOOL_POLICIES_PATH`. Do not place domain policies inside the shared library.  
+Example:
+defaults:
+  operation_type: read_only
+  require_confirmation: false
+tool_policies:
+  alterar_plano:
+    operation_type: transactional
+    require_confirmation: true
+    requires: [new_plan_id]
+
+### Execution and compatibility
+
+- Confirmation must arrive as `confirmed: true` or `confirmation: true`; text with value `true` is not sufficient.
+- If `tool_policies.yaml` does not exist, `tool_type`, `requires`, `confirmation_required`, and `execution_policy` from `tools.yaml` remain valid.
+- Old tools without policy continue to work without behavior changes.
+- A blocked call does not reach MCP and returns metadata `blocked_by_policy`, `operation_type`, and `policy_source`.
+
+### Read-only and transactional policies
+
+> Content consolidated from `Documentacao/README_TOOL_POLICIES.md`.
+
+### Goal
+
+The framework distinguishes query operations (`read_only`) from operations that change state (`transactional`) immediately before the MCP call. This classification does not replace authorization, idempotency, or MCP-server business rules; it only adds minimal conversational protection, especially explicit confirmation.
+
+### Where to configure
+
+Configuration belongs to the application backend:
+
+```text
+templates/agent_template_backend/config/tool_policies.yaml
+```
+
+The shared library contains only the loader and validation. The path is optional:
+
+```dotenv
+TOOL_POLICIES_PATH=./config/tool_policies.yaml
+```
+
+### Example
 
 ```yaml
+version: 1
+
 defaults:
   operation_type: read_only
   require_confirmation: false
 
 tool_policies:
+  consultar_plano:
+    operation_type: read_only
+
   alterar_plano:
     operation_type: transactional
     require_confirmation: true
     requires: [new_plan_id]
 ```
 
-If policy configuration is absent, legacy metadata in `tools.yaml` remains valid. Old tools without a policy must keep their previous behavior.
+To execute `alterar_plano`, the arguments must contain `new_plan_id` and a literal boolean confirmation:
 
-### Confirmation contract
+```json
+{"new_plan_id": "CONTROLE_100", "confirmed": true}
+```
 
-A blocked transactional call must not reach MCP. The runtime returns policy metadata explaining why it was blocked. Confirmation must be represented by the transaction/runtime confirmation contract; a random textual field containing the word `true` is not sufficient evidence.
+`"confirmation": true` is also accepted. Strings such as `"true"` are not accepted as confirmation.
 
-### LLM-based parameter extraction
+### Compatibility
 
-Parameter extraction supports natural language and multi-turn collection. The user may provide `name=value`, a natural phrase, only the value when one parameter is unambiguously missing, or several parameters in one turn. Extraction uses the active tool/workflow schema and parameter descriptions; it must not rely on a domain-specific regex list in the framework.
+- If `tool_policies.yaml` does not exist, the framework continues to use `tool_type`, `requires`, `confirmation_required`, and `execution_policy` from `tools.yaml`.
+- Old tools without policy continue to execute as before.
+- An explicit policy in the new file takes precedence for that tool's `operation_type` and confirmation.
+- The `tools.yaml` catalog remains the source for endpoint, schema, enablement, and cache.
+- The new file must not be placed in `libs/agent_framework`, because decisions vary by application and domain.
 
-Extracted values are merged into the active transaction before generic rerouting decisions. If extraction cannot determine a required value reliably, the agent asks for the missing parameter rather than inventing it.
+### Execution flow
 
-### MCP Server implementation
+```text
+agente -> MCPToolRouter -> validação da política -> mapeamento de parâmetros -> MCP Gateway/Server
+```
 
-A server exposes a tool catalog/schema and a call endpoint/transport. The business implementation validates the arguments, invokes the backend and returns a structured success/error result. Transactional services should implement authorization/idempotency as appropriate to the backend contract.
+A blocked call returns `ok=false`, `metadata.blocked_by_policy=true`, the operation type, and the policy source. The MCP server remains the final authority for authentication, authorization, validation, idempotency, and business transaction.
 
-### Security and observability checklist
+### Recommended migration
 
-- Explicit schema and description for every tool.
-- Explicit confirmation for configured side effects.
-- Tool allowlist per agent.
-- Sensitive-result sanitization/masking before user presentation.
-- Trace/span/event for each MCP invocation.
-- Configured timeouts/retries.
-- Do not expose MCP Servers publicly without authentication, TLS and network controls.
-- Separate read-only and transactional operations.
+1. Update the library without creating the file: legacy behavior remains.
+2. Create `config/tool_policies.yaml` in the backend.
+3. Initially register only transactional operations that require confirmation.
+4. Test calls without confirmation, with boolean confirmation, and with missing required fields.
+5. Gradually remove duplicate confirmation settings from `tools.yaml` when all consuming templates already use the new configuration.
 
-Recommended telemetry includes tenant, agent, session, tool, MCP server, latency, success/error and argument-key metadata without leaking sensitive values.
 
-### Source material consolidated
+### Minimum transactional runtime (binding fix)
+
+The routing `mcp_tools` list is an **allowlist**, not an instruction to execute every tool. The runtime now:
+
+1. automatically executes only `read_only` tools;
+2. selects at most one transactional action compatible with the user's request;
+3. when `require_confirmation: true`, persists `pending_tool_call` and `transaction_status: AWAITING_CONFIRMATION`;
+4. on the confirmation turn, reuses the same call and executes it with `confirmed: true`;
+5. publishes `available_mcp_tools`, `selected_tool_call`, `tool_policy_result`, `confirmation_required`, and `confirmation_received` in state.
+
+For the example scenario, order `123` (or `PED-ENTREGUE`) returns `ENTREGUE` in Retail MCP. Use:
+
+```text
+Quero devolver o pedido 123 porque me arrependi da compra.
+Sim, confirmo a devolução.
+```
+
+The MCP contract was standardized to use `reason` in both the catalog and FastMCP server. `tool_policies.yaml` takes precedence over legacy fields in `tools.yaml`; these remain aligned in the templates for compatibility.
+
+### Tool-policy integration and compatibility
+
+> Content consolidated from `Documentacao/RELEASE_NOTES_TOOL_POLICIES.md`.
+
+### Changes
+
+- New optional `ToolPolicyRegistry` in the shared library.
+- Central validation in `MCPToolRouter`, including direct calls.
+- Minimum types `read_only` and `transactional`.
+- Strict confirmation through `confirmed: true` or `confirmation: true`.
+- Optional support for required fields per policy.
+- Automatic fallback to `tool_type`, `requires`, `confirmation_required`, and `execution_policy` from `tools.yaml`.
+- `config/tool_policies.yaml` and the `TOOL_POLICIES_PATH` variable in the main templates, Day Zero, and `Tuning-Performance/Normal` and `Tuning-Performance/Route_Stickness` variants.
+- Unit policy and compatibility tests added in `tests/unit/test_tool_policies.py`.
+
+### Checks performed
+
+- Compilation of `libs`, `templates`, `Tuning-Performance`, and `tests`: passed.
+- Structural validation of the six YAML files: passed.
+- Isolated loader cases (transactional policy, confirmation, missing file, and missing registration): passed.
+- Rendering of both updated Word manuals: passed, with no clipping or overlap on the added pages.
+
+### Validation-environment limitation
+
+The `pytest` suite was prepared but could not be fully executed in this environment because `pytest` and project runtime dependencies were not installed and access to the package index timed out. To reproduce in a project environment:
+
+```bash
+PYTHONPATH=libs/agent_framework/src:templates/agent_template_backend python -m pytest -q
+```
+
+### Backend/MCP integration correction
+- `mcp_tools` is now treated as an allowlist.
+- Actions are no longer automatically executed together with queries.
+- Transactional confirmation is persisted and resumed on the next turn.
+- `reason`/`motivo` incompatibility in Retail MCP was corrected.
+- A deterministic delivered order was added for tests (`123`).
+- The generic keyword `produto` was removed from the Telecom intent to avoid collisions with Retail returns.
+- `Normal` and `Route_Stickness` templates in `Tuning-Performance` were synchronized.
+
+### Contextual MCP parameter extraction
+
+> Content consolidated from `Documentacao/RELEASE_NOTES_MCP_PARAMETER_EXTRACTION_FIX.md`.
+
+### Problem fixed
+
+The `extract` block in `mcp_parameter_mapping.yaml` existed in configuration and documentation, but it was not executed by the runtime. In addition, Business Context values could overwrite explicit arguments, causing `contract_key` to replace the `order_id` provided by the user.
+
+### Fixes
+
+- implementation of generic `strategy: llm` extraction after tool selection;
+- preserved support for `strategy: month_name_pt`;
+- dedicated `mcp_parameter_extraction` profile;
+- `llm.mcp_parameter_extraction` telemetry;
+- `extract` is no longer interpreted as simple mapping;
+- explicit/extracted arguments take precedence over Business Context;
+- removal of `contract_key: order_id` from templates;
+- `order_id` configured as `string`;
+- update of `Tuning-Performance` variants.
+
+### Expected result
+
+For the message `consultar pedido 123`, the MCP call must receive `order_id=123`, even when Business Context contains a different `contract_key`.
+
+### Local use of MCP tools
+
+> Content consolidated from `Documentacao/README_MCP.md`.
+
+This version adds an MCP layer to the framework:
+
+- `agent_framework.mcp.MCPToolRouter`
+- `agent_template_backend/config/mcp_servers.yaml`
+- `agent_template_backend/config/tools.yaml`
+- `mcp_servers/telecom_mcp_server`
+- `mcp_servers/retail_mcp_server`
+
+### Start locally
+
+Terminal 1:
+
+```bash
+bash ./scripts/run_mcp_servers.sh
+```
+
+Terminal 2:
+
+```bash
+cd agent_template_backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ../agent_framework
+pip install -r requirements.txt
+uvicorn app.main:app --reload --reload-dir app --reload-dir config --port 8000
+```
+
+Terminal 3:
+
+```bash
+cd agent_frontend
+python -m http.server 5173
+```
+
+### Quick tests
+
+List MCP tools loaded by the backend:
+
+```bash
+curl http://localhost:8000/debug/mcp/tools
+```
+
+Call a tool directly through the backend:
+
+```bash
+curl -X POST http://localhost:8000/debug/mcp/call/consultar_fatura \
+  -H 'Content-Type: application/json' \
+  -d '{"msisdn":"11999999999","invoice_id":"INV-001"}'
+```
+
+Telecom routing + MCP:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"session_id":"sess-tel-1","message":"Minha fatura veio alta","context":{"msisdn":"11999999999","invoice_id":"INV-001"}}}'
+```
+
+Retail routing + MCP:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"session_id":"sess-ret-1","message":"Meu pedido não chegou","context":{"order_id":"PED-1001","customer_id":"C-001"}}}'
+```
+
+### Docker Compose
+
+```bash
+docker compose up --build
+```
+
+In compose, the backend uses `config/mcp_servers.docker.yaml` to point to `telecom-mcp` and `retail-mcp`.
+
+### Read-only and transactional operations
+
+Use `config/tool_policies.yaml` in the backend to classify only operations that need additional handling. Validation is applied in the central router before the MCP Gateway/Server. The file is optional and older templates continue using the policies already present in `tools.yaml`. Full configuration and the migration procedure are in [README_TOOL_POLICIES.md](README_TOOL_POLICIES.md).
+
+### Source files
+
+The files below were consolidated into this manual:
 
 - `Documentacao/Manual_Integracao_MCP_Servers_Agent_Framework.docx`
 - `Documentacao/README_TOOL_POLICIES.md`
@@ -115,717 +816,6 @@ Recommended telemetry includes tenant, agent, session, tool, MCP server, latency
 - `Documentacao/RELEASE_NOTES_MCP_PARAMETER_EXTRACTION_FIX.md`
 - `Documentacao/README_MCP.md`
 
-### Detailed normative and implementation reference
+### Maintenance rule
 
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### MCP discovery and catalog details
-
-> Consolidated from `docs/MCP_GATEWAY_DISCOVERY.md`.
-
-### Goal
-
-This evolution allows the MCP Gateway to discover tools from registered MCP Servers by reading a manifest or catalog endpoint.
-
-The framework still points to a single MCP Gateway:
-
-```env
-MCP_GATEWAY_ENABLED=true
-MCP_GATEWAY_URL=http://localhost:8300
-MCP_GATEWAY_TIMEOUT_SECONDS=60
-```
-
-The MCP Gateway can point to many MCP Servers:
-
-```text
-Agent Framework
-  -> MCP Gateway
-     -> telecom_mcp_server
-     -> retail_mcp_server
-     -> nf_items_mcp_server
-     -> any other MCP Server
-```
-
-### What is automatic
-
-After a server is registered in `apps/mcp_gateway/config/mcp_gateway.yaml` with `discover: true`, the gateway can:
-
-- call its manifest/catalog endpoint;
-- normalize the returned tool list;
-- publish the tools in `GET /v1/tools`;
-- execute the discovered tool through `POST /v1/tools/{tool_name}/invoke`.
-
-### What is still explicit
-
-The gateway does not scan the network or GitHub by itself. You still register the MCP Server endpoint in YAML.
-
-Example:
-
-```yaml
-servers:
-  nf_items:
-    enabled: true
-    discover: true
-    protocol: legacy_http
-    transport: http
-    url: http://localhost:8400/mcp
-    catalog_endpoint: /tools
-    invoke_endpoint: /tools/call
-    timeout_seconds: 30
-```
-
-If `catalog_endpoint` is omitted, the gateway tries:
-
-```text
-/.well-known/mcp-server.json
-/manifest
-/mcp/tools
-/tools/list
-/tools
-/v1/tools
-```
-
-### Expected manifest/catalog formats
-
-The gateway accepts common shapes:
-
-```json
-{
-  "server_id": "nf_items",
-  "tools": [
-    {
-      "name": "buscar_notas_por_criterios",
-      "description": "Search invoice items by criteria.",
-      "input_schema": {
-        "cliente": "string",
-        "estado": "string",
-        "preco": "number",
-        "ean": "string",
-        "margem": "number"
-      }
-    }
-  ]
-}
-```
-
-It also accepts:
-
-```json
-{"tools": [...]}
-```
-
-```json
-{"data": {"tools": [...]}}
-```
-
-```json
-{"capabilities": {"tools": [...]}}
-```
-
-### New endpoints
-
-### List discovery servers
-
-```bash
-curl http://localhost:8300/v1/discovery/servers | jq
-```
-
-### Force catalog sync
-
-```bash
-curl -X POST http://localhost:8300/v1/discovery/sync | jq
-```
-
-### List merged static + discovered tools
-
-```bash
-curl http://localhost:8300/v1/tools | jq
-```
-
-### Precedence rule
-
-Static tools configured under `tools:` override discovered tools with the same name. This allows operations teams to override timeout, cache, allowed agents, required business keys, and endpoint behavior safely.
-
-### Plugging a new MCP Server
-
-1. Start the MCP Server.
-2. Confirm that it exposes a catalog or manifest endpoint.
-3. Add it under `servers:` in `mcp_gateway.yaml` with `discover: true`.
-4. Restart the MCP Gateway or call `POST /v1/discovery/sync`.
-5. Confirm the tool appears in `GET /v1/tools`.
-6. Invoke the tool through the gateway.
-
-### Example invocation
-
-```bash
-curl -s -X POST http://localhost:8300/v1/tools/buscar_notas_por_criterios/invoke \
-  -H "Content-Type: application/json" \
-  -d '{
-    "tenant_id": "default",
-    "agent_id": "telecom_contas",
-    "channel": "web",
-    "tool_name": "buscar_notas_por_criterios",
-    "arguments": {
-      "cliente": "CLIENTE-001",
-      "estado": "SP",
-      "preco": 100.0,
-      "ean": "7890000000000",
-      "margem": 0.05
-    },
-    "business_context": {
-      "session_key": "session-001"
-    }
-  }' | jq
-```
-
-### MCP Gateway specification
-
-> Consolidated from `specs/SPEC-004-MCP-Gateway.md`.
-
-### Escopo
-
-O MCP Gateway centraliza catálogo, autorização, roteamento, execução, cache, timeout, retry, observabilidade e resposta padronizada de tools MCP.
-
-### Endpoints
-
-| Método | Endpoint | Descrição |
-|---|---|---|
-| `GET` | `/health` | Health check. |
-| `GET` | `/ready` | Readiness check. |
-| `GET` | `/v1/tools` | Catálogo de tools. |
-| `GET` | `/v1/tools/{tool_name}` | Detalhe da tool. |
-| `POST` | `/v1/tools/{tool_name}/invoke` | Execução de tool. |
-| `GET` | `/v1/servers` | Lista MCP servers. |
-
-### ToolInvocation
-
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "tool_name": "consultar_fatura",
-  "arguments": {
-    "msisdn": "11999999999",
-    "invoice_id": "3000131180",
-    "session_id": "default:telecom_contas:session-001"
-  },
-  "business_context": {
-    "customer_key": "11999999999",
-    "contract_key": "3000131180",
-    "session_key": "session-001"
-  },
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
-```
-
-### ToolResult
-
-```json
-{
-  "tool_name": "consultar_fatura",
-  "ok": true,
-  "data": {
-    "invoice_id": "3000131180",
-    "valor_total": 249.90,
-    "vencimento": "2026-06-10",
-    "status": "ABERTA"
-  },
-  "cache": {
-    "hit": false,
-    "ttl_seconds": 300
-  },
-  "latency_ms": 140,
-  "metadata": {
-    "server": "telecom"
-  }
-}
-```
-
-### mcp_servers.yaml
-
-```yaml
-servers:
-  telecom:
-    transport: http
-    url: http://telecom-mcp:8001/mcp
-    enabled: true
-    timeout_seconds: 30
-
-  retail:
-    transport: http
-    url: http://retail-mcp:8002/mcp
-    enabled: true
-    timeout_seconds: 30
-```
-
-### tools.yaml
-
-```yaml
-tools:
-  consultar_fatura:
-    server: telecom
-    enabled: true
-    idempotent: true
-    cache_ttl_seconds: 300
-    allowed_agents:
-      - telecom_contas
-    required_business_keys:
-      - customer_key
-      - contract_key
-
-  solicitar_devolucao:
-    server: retail
-    enabled: true
-    idempotent: false
-    requires_confirmation: true
-    allowed_agents:
-      - retail_orders
-```
-
-### mcp_parameter_mapping.yaml
-
-```yaml
-tools:
-  consultar_fatura:
-    map:
-      customer_key: msisdn
-      contract_key: invoice_id
-      interaction_key: ura_call_id
-      session_key: session_id
-```
-
-### Autorização
-
-```yaml
-authorization:
-  default_policy: deny
-  agents:
-    telecom_contas:
-      allowed_tools:
-        - consultar_fatura
-        - consultar_pagamentos
-        - consultar_plano
-```
-
-### Cache
-
-| Regra | Valor |
-|---|---|
-| Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
-| Aplicação | Apenas tools idempotentes |
-| Bypass | `metadata.cache_bypass=true` |
-| TTL | `cache_ttl_seconds` |
-| Escrita | Não cachear operações mutáveis |
-
-### Retry e Timeout
-
-```yaml
-execution:
-  default_timeout_seconds: 30
-  retry:
-    enabled: true
-    max_attempts: 2
-    backoff_ms: 250
-  circuit_breaker:
-    enabled: true
-    failure_threshold: 5
-    recovery_seconds: 60
-```
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `mcp.tool.requested` | Tool requisitada. |
-| `mcp.tool.authorized` | Autorização aprovada. |
-| `mcp.tool.denied` | Autorização negada. |
-| `mcp.tool.started` | Execução iniciada. |
-| `mcp.tool.completed` | Execução concluída. |
-| `mcp.tool.failed` | Execução falhou. |
-| `mcp.cache.hit` | Cache hit. |
-| `mcp.cache.miss` | Cache miss. |
-
-### Métricas
-
-| Métrica | Dimensões |
-|---|---|
-| `mcp_tool_calls_total` | tool, server, tenant, agent, status |
-| `mcp_tool_latency_ms` | tool, server |
-| `mcp_tool_errors_total` | tool, server, error_type |
-| `mcp_cache_hits_total` | tool |
-| `mcp_cache_misses_total` | tool |
-
-### Segurança
-
-- Tools são negadas por padrão.
-- Argumentos sensíveis são mascarados.
-- Tools mutáveis exigem confirmação quando configurado.
-- MCP servers não recebem payload bruto de canal.
-- Credenciais de backend são mantidas nos MCP servers ou secret store.
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Catálogo de tools retorna tools habilitadas.
-- [ ] ToolInvocation é validado antes da execução.
-- [ ] Autorização por agente é aplicada.
-- [ ] Parâmetros são derivados do BusinessContext.
-- [ ] Cache só é aplicado a tools idempotentes.
-- [ ] Timeout/retry/circuit breaker são configuráveis.
-- [ ] Eventos e métricas são emitidos.
-- [ ] Falhas retornam ToolResult padronizado.
-- [ ] MCP servers são substituíveis por configuração.
-- [ ] Tools críticas possuem testes de contrato.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Política mínima de operação
-
-Antes de encaminhar uma tool, o runtime deve aplicar a política opcional do backend em `config/tool_policies.yaml`. Os tipos canônicos são `read_only` e `transactional`; esta última pode exigir confirmação booleana explícita e campos obrigatórios. A ausência do arquivo não é erro e preserva os campos legados de `tools.yaml`. A política conversacional não substitui autenticação, autorização, idempotência nem atomicidade no MCP Server.
-
-### Agent tool integration requirements
-
-> Consolidated from `specs/SPEC-010-Agent-Development.md`.
-
-### Escopo
-
-Esta SPEC define o padrão para criação de agentes usando templates, configuração YAML, BusinessContext, MCP, guardrails, judges, RAG, memória, observabilidade e evals.
-
-### Estrutura do Template
-
-```text
-templates/agent_template_backend/
-├── app/
-│   ├── main.py
-│   ├── state.py
-│   ├── workflows/
-│   │   └── agent_graph.py
-│   ├── agents/
-│   │   ├── runtime.py
-│   │   └── domain_agent.py
-│   └── examples/
-├── config/
-│   ├── agents.yaml
-│   ├── routing.yaml
-│   ├── tools.yaml
-│   ├── mcp_servers.yaml
-│   ├── mcp_parameter_mapping.yaml
-│   ├── identity.yaml
-│   ├── guardrails.yaml
-│   ├── judges.yaml
-│   ├── prompt_policy.yaml
-│   └── agents/<agent_id>/
-├── Dockerfile
-├── requirements.txt
-└── .env.example
-```
-
-### Responsabilidades do Framework
-
-- LangGraph;
-- memória;
-- checkpoint;
-- sessão;
-- router;
-- supervisor;
-- guardrails;
-- judges;
-- telemetry;
-- MCP integration;
-- RAG genérico;
-- cache;
-- providers LLM;
-- event bus.
-
-### Responsabilidades do Agente
-
-- prompts de domínio;
-- regras de negócio;
-- schemas específicos;
-- decisão de uso de evidências;
-- tratamento de campos obrigatórios;
-- mensagens de domínio;
-- ICs de jornada;
-- datasets de eval específicos.
-
-### Registro do Agente
-
-```yaml
-agents:
-  financeiro_agent:
-    enabled: true
-    description: "Agente financeiro"
-    profile: financeiro_agent
-    rag_namespace: financeiro
-    allowed_tools:
-      - consultar_fatura
-      - consultar_pagamentos
-```
-
-### Roteamento
-
-```yaml
-intents:
-  financeiro_consulta_fatura:
-    route: financeiro_agent
-    keywords:
-      - fatura
-      - boleto
-      - cobrança
-    mcp_tools:
-      - consultar_fatura
-```
-
-### Tool Mapping
-
-```yaml
-tools:
-  consultar_fatura:
-    map:
-      customer_key: msisdn
-      contract_key: invoice_id
-      interaction_key: ura_call_id
-      session_key: session_id
-```
-
-### Classe de Agente
-
-```python
-class FinanceiroAgent(AgentRuntimeMixin):
-    name = "financeiro_agent"
-
-    def __init__(
-        self,
-        llm,
-        telemetry=None,
-        tool_router=None,
-        rag_service=None,
-        cache=None,
-        settings=None,
-        observer=None,
-        memory=None,
-        summary_memory=None,
-    ):
-        self.llm = llm
-        self.telemetry = telemetry
-        self.tool_router = tool_router
-        self.rag_service = rag_service
-        self.cache = cache
-        self.settings = settings
-        self.observer = observer
-        self.memory = memory
-        self.summary_memory = summary_memory
-
-    async def run(self, state):
-        await self._emit_ic("IC.FINANCEIRO_AGENT_STARTED", state, {})
-        tool_context = await self._collect_mcp_context(state)
-        rag_context, rag_metadata = await self._retrieve_rag_context(state)
-        response = await self._invoke_llm_cached(
-            state,
-            "FinanceiroAgent",
-            [
-                {"role": "system", "content": "Você é um agente financeiro."},
-                {"role": "user", "content": state.get("sanitized_input") or state.get("user_text", "")},
-            ],
-        )
-        await self._emit_ic("IC.FINANCEIRO_AGENT_COMPLETED", state, {})
-        return {
-            "response_text": response,
-            "mcp_results": tool_context,
-            "rag_metadata": rag_metadata,
-        }
-```
-
-### Ordem de Confiança dos Dados
-
-1. `tool_arguments`
-2. `business_context`
-3. `context`
-4. `session.metadata`
-5. `state`
-6. extração complementar do texto
-
-### Prompt Policy
-
-```yaml
-prompt_policy:
-  system_prompt_path: prompts/system.md
-  response_style: concise
-  require_evidence: true
-  allow_tool_usage: true
-```
-
-### Guardrails por Agente
-
-```yaml
-input:
-  - code: FIN_INPUT_POLICY
-    enabled: true
-    mode: observe
-
-output:
-  - code: FIN_OUTPUT_COMPLIANCE
-    enabled: true
-    mode: enforce
-```
-
-### Judges por Agente
-
-```yaml
-judges:
-  - name: response_quality
-    enabled: true
-    threshold: 0.75
-  - name: groundedness
-    enabled: true
-    threshold: 0.70
-```
-
-### Dataset de Eval
-
-```yaml
-dataset:
-  name: financeiro_agent_regression
-  version: 1.0.0
-  items:
-    - id: fin-001
-      input: "Quero consultar minha fatura"
-      business_context:
-        customer_key: "11999999999"
-        contract_key: "3000131180"
-      expected:
-        route: financeiro_agent
-        tools:
-          - consultar_fatura
-        min_scores:
-          quality: 0.75
-          groundedness: 0.70
-```
-
-
-### Contrato obrigatório para agentes transacionais
-
-Ao criar um agente que usa tools transacionais do framework, o desenvolvedor não deve criar um motor paralelo de coleta/confirmação. Deve reutilizar `AgentRuntime` e garantir que o `AgentState` do host mantenha o latch durável:
-
-```python
-active_transaction: dict[str, Any]
-last_transaction: dict[str, Any]
-```
-
-Durante uma transação ativa, parâmetros já coletados são preservados e novos valores são mesclados incrementalmente. Em `COLLECTING_PARAMETERS`, uma resposta que satisfaz um parâmetro pendente tem precedência sobre keywords genéricas. Mudanças de intenção explícitas e inequívocas continuam permitidas.
-
-Antes de publicar um novo template/host, execute os cenários multi-turno descritos no [`Transaction State Developer Guide`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
-
-
-### Testes
-
-| Teste | Escopo |
-|---|---|
-| Unitário | Classe do agente. |
-| Routing | Intent e rota. |
-| MCP Mapping | BusinessContext para argumentos. |
-| Guardrails | Entrada e saída. |
-| Judges | Scores mínimos. |
-| Runtime | Execução completa. |
-| Memory | Continuidade de conversa. |
-| Checkpoint | Resume/replay. |
-| Observability | Trace e eventos. |
-| Certification | Evidências finais. |
-
-### Definition of Done
-
-- agente registrado;
-- rota configurada;
-- tools declaradas;
-- mapping definido;
-- prompts versionados;
-- guardrails configurados;
-- judges configurados;
-- dataset criado;
-- testes executados;
-- traces gerados;
-- certification suite aprovada;
-- documentação do agente atualizada.
-
-### Anti-patterns
-
-- agente criando sessão;
-- agente abrindo SSE;
-- agente compilando LangGraph;
-- agente chamando sistema externo diretamente;
-- prompt hardcoded sem política;
-- lógica genérica duplicada no agente;
-- payload bruto de canal dentro do agente;
-- ausência de dataset de eval.
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Novo agente é criado sem alterar core do framework.
-- [ ] Se houver transações multi-turno, `AgentState` declara `active_transaction` e `last_transaction`.
-- [ ] Configuração ocorre por YAML e `.env`.
-- [ ] Agente usa BusinessContext.
-- [ ] Agente acessa MCP por router/gateway.
-- [ ] Agente não conhece payload bruto de canal.
-- [ ] Guardrails e judges são configurados.
-- [ ] Dataset de eval existe.
-- [ ] Testes mínimos executam.
-- [ ] Trace completo é gerado.
-- [ ] Definition of Done é atendida.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md b/docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md
index cc50c8d..55de274 100644
--- a/docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md
+++ b/docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md
@@ -1,108 +1,1934 @@
 
-### Agent Gateway, MCP Gateway and Authentication
+### Agent Gateway, MCP Gateway, and Authentication
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **ingress governance, gateways, MCP catalog and component authentication**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **ingress governance, gateways, MCP catalog, and authentication between components**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Ingress governance, gateways, mcp catalog and component authentication.
+Ingress governance, gateways, MCP catalog, and authentication between components.
 
 ### Consolidated technical content
 
-### Agent Gateway, MCP Gateway, Local Execution and Basic Auth
+### Agent Gateway, MCP Gateway, Local Execution, and Basic Auth
 
-This is the operational integration guide for the two gateways and the reference backend/frontend.
+Operational and integration manual for the gateways, including responsibilities, tool catalog, discovery, startup order, ports, variables, end-to-end Basic Auth, and troubleshooting.
 
-### Responsibility model
+### How to use this document
 
-The Agent Gateway is the governed ingress for agent requests. It may apply authentication, routing/governance metadata, model/profile policy, rate limits, audit and evaluation hooks before calling the agent backend.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-The agent backend/runtime executes the LangGraph workflow and agent logic.
+### Official gateway architecture
 
-The MCP Gateway is the centralized tool catalog/execution boundary. It talks to one or more MCP Servers and applies tool-level governance such as server mapping, catalog synchronization, timeout/retry/cache behavior and authentication.
+> Content consolidated from `Documentacao/MANUAL_AGENT_PLATFORM_GATEWAYS.md`.
 
-### Expected local chain
+### Goal
 
-Client/Frontend → Agent Gateway → Agent Template Backend → MCP Gateway → MCP Server(s).
+This document consolidates:
+- Official architecture
+- Component inventory
+- Complete local-execution procedure
+- MCP Gateway
+- Agent Gateway
+- Backend Runtime
+- Frontend
+- E2E tests
+- Troubleshooting
+- Architectural decisions
 
-Each component should be started and tested independently before validating the full chain. Do not configure the backend to bypass the MCP Gateway when centralized governance is expected.
+---
 
-### MCP discovery
+### Official Architecture
 
-Discovery is automatic only for servers explicitly registered with discovery enabled. The gateway fetches their manifest/catalog, normalizes discovered tools and merges them with static configuration. Discovery does not scan the network or repository for arbitrary MCP Servers.
+Frontend (5173)
+↓
+Agent Gateway (9000)
+↓
+Agent Template Backend / Runtime (8000)
+↓
+MCP Gateway (8300)
+↓
+Telecom MCP Server (8100)
+Retail MCP Server (8200)
 
-Static tool definitions have precedence over discovered metadata with the same tool name, allowing explicit operational overrides.
+---
 
-The gateway exposes endpoints to inspect discovery servers, force synchronization and list the merged tool catalog. Use these endpoints before debugging an agent prompt when a tool appears to be missing.
+### Official Ports
 
-### Basic Auth trust boundaries
+| Component | Port |
+|------------|--------|
+| Frontend | 5173 |
+| Agent Gateway | 9000 |
+| Backend Runtime | 8000 |
+| MCP Gateway | 8300 |
+| Telecom MCP Server | 8100 |
+| Retail MCP Server | 8200 |
 
-Use separate credential pairs for each hop:
+---
 
-1. external client/TIA → Agent Gateway;
-2. Agent Gateway → agent backend;
-3. agent backend → MCP Gateway.
+### Official Variables
 
-Each receiving component validates its own pair; each sending component is configured with the downstream credentials. This separation allows credentials to be rotated independently and makes failures diagnosable by hop.
+### Agent Template Backend
 
-Do not confuse inbound credentials with outbound credentials. A working login to the Agent Gateway says nothing about the gateway's credentials for the backend.
+ENABLE_MCP_TOOLS=true
 
-### Startup validation sequence
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default
 
-1. Start MCP Servers and call each `/health` endpoint.
-2. Start MCP Gateway and inspect health + merged tool list.
-3. Start agent backend and verify it points to the MCP Gateway.
-4. Start Agent Gateway and verify backend connectivity.
-5. Start frontend/channel integration and verify it targets the Agent Gateway.
-6. Run an end-to-end read-only tool call.
-7. Run a transactional policy/confirmation test if applicable.
+### Agent Gateway
 
-### Troubleshooting by symptom
+DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
 
-**MCP tool absent from catalog:** verify server registration, `enabled`, discovery flag, manifest endpoint and sync result; then check static/discovered name collisions.
+### MCP Gateway
 
-**Backend calls MCP Server directly:** correct the MCP base URL so the runtime targets MCP Gateway, not a domain server.
+MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
 
-**Agent Gateway cannot reach backend:** verify backend URL/port, container DNS, inbound backend credentials and gateway outbound credentials.
+---
 
-**401 on external request:** validate client→Agent Gateway pair.
+### Startup Order
 
-**401 between gateway and backend:** validate Agent Gateway outbound pair and backend inbound pair.
+1. Telecom MCP Server
+2. Retail MCP Server
+3. MCP Gateway
+4. Agent Template Backend
+5. Agent Gateway
+6. Frontend
 
-**401 from backend to MCP Gateway:** validate backend outbound pair and MCP Gateway inbound pair.
+---
 
-**Frontend uses wrong port:** treat frontend URL configuration as a channel concern and keep it pointed at Agent Gateway in the governed topology.
+### Terminal 1 — Telecom MCP Server
 
-### Source material consolidated
+cd mcp/servers/telecom_mcp_server
 
-- `Documentacao/MANUAL_AGENT_PLATFORM_GATEWAYS.md`
-- `Documentacao/MANUAL_EXECUCAO_AGENT_GATEWAY_MCP_GATEWAY_FRONTEND.md`
-- `Documentacao/Implementando_Basic_Auth.md`
-- `docs/MCP_GATEWAY_DISCOVERY.md`
-- `Documentacao/MCP_GATEWAY_RUNBOOK.md`
-- `Documentacao/README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md`
-- `Documentacao/INVENTARIO_AGENT_GATEWAY_MCP_GATEWAY.md`
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
 
-### Detailed normative and implementation reference
+python -m uvicorn main:app --host 0.0.0.0 --port 8100 --reload
 
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
+Validation:
 
-### MCP Gateway discovery and catalog sync
+curl http://localhost:8100/health
 
-> Consolidated from `docs/MCP_GATEWAY_DISCOVERY.md`.
+---
+
+### Terminal 2 — Retail MCP Server
+
+cd mcp/servers/retail_mcp_server
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+python -m uvicorn main:app --host 0.0.0.0 --port 8200 --reload
+
+Validation:
+
+curl http://localhost:8200/health
+
+---
+
+### Terminal 3 — MCP Gateway
+
+cd apps/mcp_gateway
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
+
+Validations:
+
+curl http://localhost:8300/health
+curl http://localhost:8300/ready
+curl http://localhost:8300/v1/tools
+
+Test:
+
+curl -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke
+
+---
+
+### Terminal 4 — Agent Template Backend
+
+cd templates/agent_template_backend
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+
+Validations:
+
+curl http://localhost:8000/health
+curl http://localhost:8000/agents
+
+---
+
+### Terminal 5 — Agent Gateway
+
+cd apps/agent_gateway
+
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+
+python -m uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
+
+Validations:
+
+curl http://localhost:9000/health
+
+Test:
+
+curl -X POST http://localhost:9000/gateway/message
+
+---
+
+### Terminal 6 — Frontend
+
+cd agent_frontend
+
+npm install
+
+npm run dev -- --host 0.0.0.0 --port 5173
+
+Open:
+
+http://localhost:5173
+
+Backend URL:
+
+http://localhost:9000
+
+---
+
+### Tool Flow
+
+Agent
+↓
+MCPToolRouter
+↓
+MCPGatewayClient
+↓
+MCP Gateway
+↓
+MCP Server
+
+---
+
+### Integrated E2E Test
+
+Frontend
+↓
+Agent Gateway
+↓
+Backend Runtime
+↓
+MCP Gateway
+↓
+Telecom MCP Server
+
+Expected result:
+
+- Agent Gateway receives the request
+- Runtime executes LangGraph
+- MCP Gateway resolves the tool
+- MCP Server responds
+- User receives the response
+
+---
+
+### Troubleshooting
+
+### Backend calling MCP Server directly
+
+Confirm:
+
+MCP_GATEWAY_ENABLED=true
+
+MCP_GATEWAY_URL=http://localhost:8300
+
+### Incorrect port
+
+The official MCP Gateway port is:
+
+8300
+
+### Agent Gateway cannot find Backend
+
+Validate:
+
+curl http://localhost:8000/health
+
+### MCP Gateway cannot find MCP Server
+
+Validate:
+
+curl http://localhost:8100/health
+curl http://localhost:8200/health
+
+---
+
+### Official Architectural Decisions
+
+- Agent Gateway centralizes governance
+- Runtime executes LangGraph
+- Runtime executes LLM
+- MCP Gateway centralizes tools
+- MCP Servers execute tools
+- Backend uses MCP Gateway
+- `gateway_runtime.env.example` was removed
+- `MCP_GATEWAY_*` stays in the backend `.env`
+- Official MCP Gateway port = 8300
+
+### Integrated local execution
+
+> Content consolidated from `Documentacao/MANUAL_EXECUCAO_AGENT_GATEWAY_MCP_GATEWAY_FRONTEND.md`.
+
+### Agent Gateway + MCP Gateway + Agent Template Backend + Frontend
+
+### 1. Execution architecture
+
+The local architecture is:
+
+```text
+Frontend
+  porta 5173
+    │
+    ▼
+Agent Gateway
+  porta 9000
+    │
+    ▼
+Agent Template Backend / Agent Runtime
+  porta 8000
+    │
+    ▼
+MCP Gateway
+  porta 8300
+    │
+    ▼
+MCP Server / Mock Telecom MCP
+  porta 8001
+```
+
+Model governance, rate limiting, audit, and policies live in the **Agent Gateway**.
+
+The **Agent Runtime / Agent Template Backend** remains responsible for:
+
+- LangGraph;
+- state;
+- memory;
+- checkpoints;
+- supervisor/router;
+- guardrails;
+- judges;
+- LLM calls through existing providers;
+- tool calls through MCP Gateway.
+
+---
+
+### 2. Ports
+
+| Component | Port | URL |
+|---|---:|---|
+| Frontend | 5173 | `http://localhost:5173` |
+| Agent Gateway | 9000 | `http://localhost:9000` |
+| Agent Template Backend | 8000 | `http://localhost:8000` |
+| MCP Gateway | 8300 | `http://localhost:8300` |
+| MCP Server / Mock Telecom MCP | 8001 | `http://localhost:8001` |
+
+---
+
+### 3. Recommended startup order
+
+Start in this order:
+
+1. MCP Server / Mock Telecom MCP
+2. MCP Gateway
+3. Agent Template Backend
+4. Agent Gateway
+5. Frontend
+
+---
+
+### 4. Terminal 1 — MCP Server / Mock Telecom MCP
+
+If you are using the mock included in the overlay:
+
+```bash
+cd agent_platform_oci/mcp/servers/mock_telecom_mcp
+
+python -m venv .venv
+source .venv/bin/activate
+
+pip install -r requirements.txt
+
+uvicorn app:app --host 0.0.0.0 --port 8001 --reload
+```
+
+Validate:
+
+```bash
+curl http://localhost:8001/health
+```
+
+Expected result:
+
+```json
+{
+  "status": "ok",
+  "service": "mock_telecom_mcp"
+}
+```
+
+---
+
+### 5. Terminal 2 — MCP Gateway
+
+```bash
+cd agent_platform_oci/apps/mcp_gateway
+
+python -m venv .venv
+source .venv/bin/activate
+
+pip install -r requirements.txt
+
+export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+
+uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
+```
+
+Validate health:
+
+```bash
+curl http://localhost:8300/health
+```
+
+Validate readiness:
+
+```bash
+curl http://localhost:8300/ready
+```
+
+List tools:
+
+```bash
+curl -s http://localhost:8300/v1/tools | jq
+```
+
+Execute tool:
+
+```bash
+curl -s -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "channel": "web",
+    "tool_name": "consultar_fatura",
+    "business_context": {
+      "customer_key": "11999999999",
+      "contract_key": "INV-001",
+      "session_key": "session-001"
+    }
+  }' | jq
+```
+
+Expected result:
+
+```json
+{
+  "tool_name": "consultar_fatura",
+  "version": "1.0.0",
+  "ok": true,
+  "data": {
+    "invoice_id": "INV-001",
+    "msisdn": "11999999999",
+    "valor_total": 249.9,
+    "vencimento": "2026-06-10",
+    "status": "ABERTA"
+  }
+}
+```
+
+---
+
+### 6. Terminal 3 — Agent Template Backend / Agent Runtime
+
+```bash
+cd agent_platform_oci/templates/agent_template_backend
+```
+
+or, if your backend is in another folder:
+
+```bash
+cd agent_platform_oci/templates/agent_template_backend
+```
+
+Activate environment:
+
+```bash
+source .venv/bin/activate
+```
+
+If `.venv` does not exist yet:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Configure variables:
+
+```bash
+export MCP_GATEWAY_ENABLED=true
+export MCP_GATEWAY_URL=http://localhost:8300
+export MCP_GATEWAY_TIMEOUT_SECONDS=60
+
+export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+```
+
+If you are using OCI/OpenAI-compatible, also keep the backend's existing variables:
+
+```bash
+export LLM_PROVIDER=oci_openai
+export OCI_GENAI_API_KEY=<sua-chave>
+```
+
+or, for mock:
+
+```bash
+export LLM_PROVIDER=mock
+```
+
+Start backend:
+
+```bash
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+Validate:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Validate agents:
+
+```bash
+curl http://localhost:8000/agents | jq
+```
+
+Test backend directly:
+
+```bash
+curl -s -X POST http://localhost:8000/gateway/message \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "payload": {
+      "message": "Quero consultar minha fatura",
+      "session_id": "session-001",
+      "user_id": "user-001",
+      "message_id": "msg-001",
+      "business_context": {
+        "customer_key": "11999999999",
+        "contract_key": "INV-001",
+        "session_key": "session-001"
+      }
+    }
+  }' | jq
+```
+
+---
+
+### 7. Terminal 4 — Agent Gateway
+
+```bash
+cd agent_platform_oci/apps/agent_gateway
+```
+
+Activate environment:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Configure variables:
+
+```bash
+export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+```
+
+Start Agent Gateway:
+
+```bash
+python -m uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
+```
+
+Validate:
+
+```bash
+curl http://localhost:9000/health
+```
+
+If the example governed route is registered in `app.main`, test:
+
+```bash
+curl -s -X POST http://localhost:9000/gateway/message/governed \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "payload": {
+      "message": "Quero consultar minha fatura",
+      "session_id": "session-001",
+      "user_id": "user-001",
+      "message_id": "msg-001",
+      "metadata": {
+        "operation": "agent.final_answer"
+      },
+      "business_context": {
+        "customer_key": "11999999999",
+        "contract_key": "INV-001",
+        "session_key": "session-001"
+      }
+    }
+  }' | jq
+```
+
+If the actual route is `/gateway/message`, test:
+
+```bash
+curl -s -X POST http://localhost:9000/gateway/message \
+  -H "Content-Type: application/json" \
+  -d '{
+    "channel": "web",
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "payload": {
+      "message": "Quero consultar minha fatura",
+      "session_id": "session-001",
+      "user_id": "user-001",
+      "message_id": "msg-001",
+      "metadata": {
+        "operation": "agent.final_answer"
+      },
+      "business_context": {
+        "customer_key": "11999999999",
+        "contract_key": "INV-001",
+        "session_key": "session-001"
+      }
+    }
+  }' | jq
+```
+
+---
+
+### 8. Terminal 5 — Frontend
+
+```bash
+cd agent_platform_oci/agent_frontend
+```
+
+or the folder where the frontend is located.
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start:
+
+```bash
+npm run dev -- --host 0.0.0.0 --port 5173
+```
+
+Open:
+
+```text
+http://localhost:5173
+```
+
+Configure in the frontend:
+
+```text
+Backend URL: http://localhost:9000
+Agent: telecom_contas
+Session ID: session-001
+Customer Key: 11999999999
+Contract Key: INV-001
+```
+
+The frontend must call the **Agent Gateway** on port 9000, not the MCP Gateway.
+
+---
+
+### 9. Expected final flow
+
+```text
+Frontend 5173
+  ↓
+Agent Gateway 9000
+  ↓
+Agent Template Backend 8000
+  ↓
+MCP Gateway 8300
+  ↓
+Mock Telecom MCP 8001
+```
+
+---
+
+### 10. Docker Compose for MCP Gateway + Mock MCP
+
+It is also possible to start MCP Gateway + Mock MCP with Docker Compose:
+
+```bash
+cd agent_platform_oci
+
+docker compose -f deploy/docker/docker-compose.mcp-gateway.yml up --build
+```
+
+This starts:
+
+```text
+MCP Gateway      http://localhost:8300
+Mock Telecom MCP http://localhost:8001
+```
+
+Then start manually:
+
+- Agent Template Backend on port 8000;
+- Agent Gateway on port 9000;
+- Frontend on port 5173.
+
+---
+
+### 11. Validation checklist
+
+### MCP Server
+
+```bash
+curl http://localhost:8001/health
+```
+
+### MCP Gateway
+
+```bash
+curl http://localhost:8300/health
+curl http://localhost:8300/v1/tools
+```
+
+### Backend Runtime
+
+```bash
+curl http://localhost:8000/health
+curl http://localhost:8000/agents
+```
+
+### Agent Gateway
+
+```bash
+curl http://localhost:9000/health
+```
+
+### Frontend
+
+```text
+http://localhost:5173
+```
+
+---
+
+### 12. Common errors
+
+### 12.1. Frontend calling the wrong port
+
+Wrong:
+
+```text
+Frontend → http://localhost:8000
+```
+
+Correct:
+
+```text
+Frontend → http://localhost:9000
+```
+
+If you want to test without Agent Gateway, you can temporarily point to port 8000. But in the final model, the frontend must use the Agent Gateway.
+
+---
+
+### 12.2. MCP Gateway without an MCP Server
+
+Symptom:
+
+```text
+MCP server unavailable
+```
+
+Fix:
+
+```bash
+curl http://localhost:8001/health
+```
+
+If it fails, start the mock MCP server.
+
+---
+
+### 12.3. Tool without BusinessContext
+
+Symptom:
+
+```json
+{
+  "missing_business_keys": ["customer_key", "contract_key"]
+}
+```
+
+Fix:
+
+send:
+
+```json
+"business_context": {
+  "customer_key": "11999999999",
+  "contract_key": "INV-001",
+  "session_key": "session-001"
+}
+```
+
+---
+
+### 12.4. Agent Gateway cannot find backend
+
+Symptom:
+
+```text
+Connection refused http://localhost:8000
+```
+
+Fix:
+
+validate:
+
+```bash
+curl http://localhost:8000/health
+```
+
+and configure:
+
+```bash
+export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+```
+
+---
+
+### 12.5. Governed route not registered
+
+If `/gateway/message/governed` returns 404, the example file has not yet been included in `app.main`.
+
+In that case, use the actual `/gateway/message` route or register it in `main.py`:
+
+```python
+from app.routes.governed_proxy_example import router as governed_router
+
+app.include_router(governed_router)
+```
+
+---
+
+### 13. Consolidated variables
+
+### Agent Gateway
+
+```env
+DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+```
+
+### Agent Template Backend
+
+```env
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+LLM_PROVIDER=mock
+```
+
+### MCP Gateway
+
+```env
+MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+```
+
+---
+
+### 14. Quick summary
+
+In five terminals:
+
+```bash
+# Terminal 1
+cd mcp/servers/mock_telecom_mcp
+source .venv/bin/activate
+uvicorn app:app --host 0.0.0.0 --port 8001 --reload
+
+# Terminal 2
+cd apps/mcp_gateway
+source .venv/bin/activate
+export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
+
+# Terminal 3
+cd templates/agent_template_backend
+source .venv/bin/activate
+export MCP_GATEWAY_ENABLED=true
+export MCP_GATEWAY_URL=http://localhost:8300
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+
+# Terminal 4
+cd apps/agent_gateway
+source .venv/bin/activate
+export DEFAULT_AGENT_BACKEND_URL=http://localhost:8000
+export AGENT_GATEWAY_GOVERNANCE_CONFIG=config/gateway_governance.yaml
+uvicorn app.main:app --host 0.0.0.0 --port 9000 --reload
+
+# Terminal 5
+cd agent_frontend
+npm install
+npm run dev -- --host 0.0.0.0 --port 5173
+```
+
+### End-to-end Basic Auth
+
+> Content consolidated from `Documentacao/Implementando_Basic_Auth.md`.
+
+To validate **the entire circuit with Basic Auth**, you need to configure three distinct trust relationships:
+
+```text
+Cliente de teste
+   └─ Basic Auth A ─► Agent Gateway :8010
+                         └─ Basic Auth B ─► Agent Backend :8000
+                                                └─ Basic Auth C ─► MCP Gateway :8300
+```
+
+There is one important detail: in the current package, Basic authentication already works for **incoming** calls, but internal clients still do not send Basic Auth:
+
+* `Agent Gateway → Agent Backend` does not send credentials;
+* `Agent Backend → MCP Gateway` sends only a Bearer Token.
+
+Therefore, to test the entire circuit with Basic Auth, make the two small code changes described below.
+
+---
+
+### 1. Prepare the environment
+
+Assume the ZIP was extracted to:
+
+```bash
+cd agent_framework_oci_authentication_v2_1
+```
+
+Create a single virtual environment to make testing easier:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+On Windows PowerShell:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+Install the framework and dependencies for the three components:
+
+```bash
+pip install -U pip
+
+pip install -e ./libs/agent_framework
+
+pip install \
+  -r ./Tuning-Performance/Authentication/agent_template_backend_authentication/requirements.txt \
+  -r ./apps/agent_gateway/requirements.txt \
+  -r ./apps/mcp_gateway/requirements.txt
+```
+
+Confirm the import:
+
+```bash
+python -c "from agent_framework.security import install_authentication; print('framework ok')"
+```
+
+---
+
+### 2. Create three Client ID and Secret pairs
+
+Use different credentials for each hop. For local testing:
+
+| Flow | Client ID | Test Secret |
+| ----------------------- | -------------------- | --------------------------- |
+| Cliente → Agent Gateway | `tia-test`           | `TiaGateway-Test-2026!`     |
+| Agent Gateway → Backend | `agent-gateway-test` | `GatewayBackend-Test-2026!` |
+| Backend → MCP Gateway   | `agent-backend-test` | `BackendMcp-Test-2026!`     |
+
+These values are for local environments only. Do not reuse them in production.
+
+### Generate the hashes
+
+The script is located at:
+
+```text
+Tuning-Performance/Authentication/
+  agent_template_backend_authentication/
+    scripts/generate_secret_hash.py
+```
+
+Run:
+
+```bash
+python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
+  --secret 'TiaGateway-Test-2026!'
+```
+
+Then:
+
+```bash
+python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
+  --secret 'GatewayBackend-Test-2026!'
+```
+
+And:
+
+```bash
+python Tuning-Performance/Authentication/agent_template_backend_authentication/scripts/generate_secret_hash.py \
+  --secret 'BackendMcp-Test-2026!'
+```
+
+You will receive three values similar to:
+
+```text
+pbkdf2_sha256:310000:<salt>:<digest>
+```
+
+Store them temporarily:
+
+```bash
+HASH_CLIENT_GATEWAY='pbkdf2_sha256:310000:...'
+HASH_GATEWAY_BACKEND='pbkdf2_sha256:310000:...'
+HASH_BACKEND_MCP='pbkdf2_sha256:310000:...'
+```
+
+The hash changes on every run because the salt is random. This is expected.
+
+---
+
+### 3. Configure the Agent Gateway
+
+Enter the directory:
+
+```bash
+cd apps/agent_gateway
+```
+
+Copy the example:
+
+```bash
+cp .env.example .env
+```
+
+Add to the end of `.env`:
+
+```env
+# Entrada: cliente/TIA -> Agent Gateway
+AGENT_GATEWAY_AUTH_ENABLED=true
+AGENT_GATEWAY_AUTH_MODE=basic
+AGENT_GATEWAY_AUTH_BASIC_CLIENT_ID=tia-test
+AGENT_GATEWAY_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_CLIENT_GATEWAY
+AGENT_GATEWAY_AUTH_BASIC_REALM=agent-gateway
+
+AGENT_GATEWAY_AUTH_PUBLIC_PATHS=/health,/docs,/openapi.json,/redoc
+AGENT_GATEWAY_AUTH_PUBLIC_PREFIXES=
+
+# Saída: Agent Gateway -> Agent Backend
+BACKEND_AUTH_MODE=basic
+BACKEND_AUTH_CLIENT_ID=agent-gateway-test
+BACKEND_AUTH_SECRET=GatewayBackend-Test-2026!
+```
+
+Do not put quotes in `.env`:
+
+```env
+BACKEND_AUTH_SECRET=GatewayBackend-Test-2026!
+```
+
+The backend configuration file already points the `contas` backend to:
+
+```yaml
+contas:
+  url: http://localhost:8000
+```
+
+File:
+
+```text
+apps/agent_gateway/config/backends.yaml
+```
+
+For this test, keep only the `contas` backend or force the backend in the payload. Otherwise, requests about offers and support may be routed to ports where no backend is running.
+
+---
+
+### 4. Make Agent Gateway send Basic Auth to the backend
+
+Open:
+
+```text
+libs/agent_framework/src/agent_framework/global_supervisor/client.py
+```
+
+Replace the `BackendClient` class with a version that supports Basic authentication.
+
+At the beginning of the file, add:
+
+```python
+import os
+```
+
+Change the constructor:
+
+```python
+class BackendClient:
+    def __init__(
+        self,
+        timeout_seconds: float = 120.0,
+        basic_client_id: str | None = None,
+        basic_secret: str | None = None,
+    ):
+        self.timeout_seconds = timeout_seconds
+        self.basic_client_id = basic_client_id
+        self.basic_secret = basic_secret
+
+    def _auth(self) -> httpx.BasicAuth | None:
+        if self.basic_client_id and self.basic_secret:
+            return httpx.BasicAuth(
+                username=self.basic_client_id,
+                password=self.basic_secret,
+            )
+        return None
+```
+
+In the `call_message` method, replace:
+
+```python
+resp = await client.post(url, json=payload)
+```
+
+with:
+
+```python
+resp = await client.post(
+    url,
+    json=payload,
+    auth=self._auth(),
+)
+```
+
+In the `health` method, you can keep `/health` public. If you also want to send authentication, use:
+
+```python
+resp = await client.get(url, auth=self._auth())
+```
+
+Now open:
+
+```text
+apps/agent_gateway/app/main.py
+```
+
+Add:
+
+```python
+import os
+```
+
+Replace:
+
+```python
+backend_client = BackendClient(
+    timeout_seconds=settings.BACKEND_TIMEOUT_SECONDS
+)
+```
+
+with:
+
+```python
+backend_client = BackendClient(
+    timeout_seconds=settings.BACKEND_TIMEOUT_SECONDS,
+    basic_client_id=os.getenv("BACKEND_AUTH_CLIENT_ID"),
+    basic_secret=os.getenv("BACKEND_AUTH_SECRET"),
+)
+```
+
+This implements:
+
+```text
+Agent Gateway → Agent Backend
+Authorization: Basic base64(agent-gateway-test:GatewayBackend-Test-2026!)
+```
+
+---
+
+### 5. Configure the authenticated Agent Backend
+
+Enter the directory:
+
+```bash
+cd Tuning-Performance/Authentication/agent_template_backend_authentication
+```
+
+Copy the example:
+
+```bash
+cp .env.example .env
+```
+
+Adjust the authentication section:
+
+```env
+# Entrada: Agent Gateway -> Agent Backend
+AGENT_AUTH_ENABLED=true
+AGENT_AUTH_MODE=basic
+AGENT_AUTH_BASIC_CLIENT_ID=agent-gateway-test
+AGENT_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_GATEWAY_BACKEND
+AGENT_AUTH_BASIC_REALM=agent-contas
+
+AGENT_AUTH_PUBLIC_PATHS=/health,/docs,/openapi.json,/redoc
+AGENT_AUTH_PUBLIC_PREFIXES=
+```
+
+To use MCP Gateway:
+
+```env
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+
+# Saída: Agent Backend -> MCP Gateway
+MCP_GATEWAY_AUTH_MODE=basic
+MCP_GATEWAY_BASIC_CLIENT_ID=agent-backend-test
+MCP_GATEWAY_BASIC_SECRET=BackendMcp-Test-2026!
+```
+
+To avoid external dependencies during the first test, also configure:
+
+```env
+LLM_PROVIDER=mock
+ENABLE_LANGFUSE=false
+ENABLE_ANALYTICS=false
+
+SESSION_REPOSITORY_PROVIDER=memory
+MEMORY_REPOSITORY_PROVIDER=memory
+CHECKPOINT_REPOSITORY_PROVIDER=memory
+CACHE_PROVIDER=memory
+USAGE_REPOSITORY_PROVIDER=memory
+```
+
+The exact names of some providers may depend on the framework's current configuration file. If `.env.example` already contains local or mock values, preserve them.
+
+---
+
+### 6. Make the Backend send Basic Auth to MCP Gateway
+
+Open:
+
+```text
+libs/agent_framework/src/agent_framework/gateways/mcp_gateway_client.py
+```
+
+Replace the implementation with:
+
+```python
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import httpx
+
+
+class MCPGatewayClient:
+    def __init__(
+        self,
+        base_url: str,
+        token: str | None = None,
+        timeout_seconds: int = 60,
+        auth_mode: str | None = None,
+        basic_client_id: str | None = None,
+        basic_secret: str | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout_seconds = timeout_seconds
+        self.auth_mode = (auth_mode or "").strip().lower()
+        self.basic_client_id = basic_client_id
+        self.basic_secret = basic_secret
+
+    def _headers(self) -> dict[str, str]:
+        if (
+            self.auth_mode == "basic"
+            and self.basic_client_id
+            and self.basic_secret
+        ):
+            raw = f"{self.basic_client_id}:{self.basic_secret}".encode("utf-8")
+            encoded = base64.b64encode(raw).decode("ascii")
+            return {"Authorization": f"Basic {encoded}"}
+
+        if self.token:
+            return {"Authorization": f"Bearer {self.token}"}
+
+        return {}
+
+    async def list_tools(self) -> dict[str, Any]:
+        async with httpx.AsyncClient(
+            timeout=self.timeout_seconds
+        ) as client:
+            response = await client.get(
+                f"{self.base_url}/v1/tools",
+                headers=self._headers(),
+            )
+            response.raise_for_status()
+            return response.json()
+
+    async def invoke_tool(
+        self,
+        *,
+        tenant_id: str,
+        agent_id: str,
+        channel: str | None,
+        tool_name: str,
+        arguments: dict[str, Any] | None = None,
+        business_context: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        payload = {
+            "tenant_id": tenant_id,
+            "agent_id": agent_id,
+            "channel": channel,
+            "tool_name": tool_name,
+            "arguments": arguments or {},
+            "business_context": business_context or {},
+            "metadata": metadata or {},
+        }
+
+        async with httpx.AsyncClient(
+            timeout=self.timeout_seconds
+        ) as client:
+            response = await client.post(
+                f"{self.base_url}/v1/tools/{tool_name}/invoke",
+                json=payload,
+                headers=self._headers(),
+            )
+            response.raise_for_status()
+            return response.json()
+```
+
+Now open:
+
+```text
+libs/agent_framework/src/agent_framework/mcp/tool_router.py
+```
+
+Locate:
+
+```python
+MCPGatewayClient(
+    base_url=getattr(
+        settings,
+        "MCP_GATEWAY_URL",
+        "http://localhost:8300",
+    ),
+    token=getattr(settings, "MCP_GATEWAY_TOKEN", None),
+    timeout_seconds=getattr(
+        settings,
+        "MCP_GATEWAY_TIMEOUT_SECONDS",
+        settings.MCP_TOOL_TIMEOUT_SECONDS,
+    ),
+)
+```
+
+Change to:
+
+```python
+MCPGatewayClient(
+    base_url=getattr(
+        settings,
+        "MCP_GATEWAY_URL",
+        "http://localhost:8300",
+    ),
+    token=getattr(settings, "MCP_GATEWAY_TOKEN", None),
+    timeout_seconds=getattr(
+        settings,
+        "MCP_GATEWAY_TIMEOUT_SECONDS",
+        settings.MCP_TOOL_TIMEOUT_SECONDS,
+    ),
+    auth_mode=getattr(
+        settings,
+        "MCP_GATEWAY_AUTH_MODE",
+        None,
+    ),
+    basic_client_id=getattr(
+        settings,
+        "MCP_GATEWAY_BASIC_CLIENT_ID",
+        None,
+    ),
+    basic_secret=getattr(
+        settings,
+        "MCP_GATEWAY_BASIC_SECRET",
+        None,
+    ),
+)
+```
+
+Add these fields in:
+
+```text
+libs/agent_framework/src/agent_framework/config/settings.py
+```
+
+Near the existing MCP Gateway settings:
+
+```python
+MCP_GATEWAY_AUTH_MODE: str | None = None
+MCP_GATEWAY_BASIC_CLIENT_ID: str | None = None
+MCP_GATEWAY_BASIC_SECRET: str | None = None
+```
+
+There is also a local factory in:
+
+```text
+Tuning-Performance/Authentication/
+  agent_template_backend_authentication/
+    app/mcp_gateway_client_factory.py
+```
+
+Adjust it to:
+
+```python
+from __future__ import annotations
+
+import os
+
+from agent_framework.gateways import MCPGatewayClient
+
+
+def build_mcp_gateway_client() -> MCPGatewayClient | None:
+    if os.getenv("MCP_GATEWAY_ENABLED", "true").lower() != "true":
+        return None
+
+    return MCPGatewayClient(
+        base_url=os.getenv(
+            "MCP_GATEWAY_URL",
+            "http://localhost:8300",
+        ),
+        token=os.getenv("MCP_GATEWAY_TOKEN") or None,
+        timeout_seconds=int(
+            os.getenv("MCP_GATEWAY_TIMEOUT_SECONDS", "60")
+        ),
+        auth_mode=os.getenv("MCP_GATEWAY_AUTH_MODE"),
+        basic_client_id=os.getenv(
+            "MCP_GATEWAY_BASIC_CLIENT_ID"
+        ),
+        basic_secret=os.getenv(
+            "MCP_GATEWAY_BASIC_SECRET"
+        ),
+    )
+```
+
+---
+
+### 7. Configure the MCP Gateway
+
+Enter the directory:
+
+```bash
+cd apps/mcp_gateway
+```
+
+Create `.env`:
+
+```bash
+cp .env.example .env
+```
+
+Add:
+
+```env
+# Entrada: Agent Backend -> MCP Gateway
+MCP_GATEWAY_AUTH_ENABLED=true
+MCP_GATEWAY_AUTH_MODE=basic
+MCP_GATEWAY_AUTH_BASIC_CLIENT_ID=agent-backend-test
+MCP_GATEWAY_AUTH_BASIC_SECRET_HASH=COLE_AQUI_HASH_BACKEND_MCP
+MCP_GATEWAY_AUTH_BASIC_REALM=mcp-gateway
+
+MCP_GATEWAY_AUTH_PUBLIC_PATHS=/health,/ready,/docs,/openapi.json,/redoc
+MCP_GATEWAY_AUTH_PUBLIC_PREFIXES=
+
+MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+```
+
+### Disable the legacy Bearer mechanism
+
+The MCP Gateway still has a second legacy mechanism, configured in:
+
+```text
+apps/mcp_gateway/config/mcp_gateway.yaml
+```
+
+Locate the section:
+
+```yaml
+auth:
+  enabled: true
+```
+
+Change to:
+
+```yaml
+auth:
+  enabled: false
+```
+
+This is necessary because the new middleware already performs Basic authentication. If the legacy `auth_check()` remains enabled, the request will pass Basic authentication and then be rejected because it does not have a Bearer Token.
+
+---
+
+### 8. Start the components
+
+Use four terminals.
+
+### Terminal 1 — MCP Servers
+
+The MCP Gateway needs at least one available MCP server to demonstrate a real call.
+
+From the project root:
+
+```bash
+source .venv/bin/activate
+```
+
+Start the telecom server:
+
+```bash
+uvicorn mcp.servers.telecom_mcp_server.main:app \
+  --host 0.0.0.0 \
+  --port 8100 \
+  --reload
+```
+
+In another terminal, if you also want retail:
+
+```bash
+uvicorn mcp.servers.retail_mcp_server.main:app \
+  --host 0.0.0.0 \
+  --port 8200 \
+  --reload
+```
+
+Check the URLs configured in:
+
+```text
+apps/mcp_gateway/config/mcp_gateway.yaml
+```
+
+For local execution, they should point to:
+
+```yaml
+url: http://localhost:8100
+```
+
+and:
+
+```yaml
+url: http://localhost:8200
+```
+
+---
+
+### Terminal 2 — MCP Gateway
+
+```bash
+cd apps/mcp_gateway
+source ../../.venv/bin/activate
+```
+
+Start it using `--env-file`. This is important because the middleware reads variables with `os.getenv()`:
+
+```bash
+uvicorn app.main:app \
+  --host 0.0.0.0 \
+  --port 8300 \
+  --reload \
+  --env-file .env
+```
+
+Test public health:
+
+```bash
+curl http://localhost:8300/health
+```
+
+Test a protected endpoint without credentials:
+
+```bash
+curl -i http://localhost:8300/v1/tools
+```
+
+Expected:
+
+```text
+HTTP/1.1 401 Unauthorized
+```
+
+Test with Basic Auth:
+
+```bash
+curl -i \
+  -u 'agent-backend-test:BackendMcp-Test-2026!' \
+  http://localhost:8300/v1/tools
+```
+
+Expected:
+
+```text
+HTTP/1.1 200 OK
+```
+
+---
+
+### Terminal 3 — Agent Backend
+
+```bash
+cd Tuning-Performance/Authentication/agent_template_backend_authentication
+source ../../../.venv/bin/activate
+```
+
+Start:
+
+```bash
+uvicorn app.main:app \
+  --host 0.0.0.0 \
+  --port 8000 \
+  --reload \
+  --env-file .env
+```
+
+Test health:
+
+```bash
+curl http://localhost:8000/health
+```
+
+Test a protected endpoint without credentials:
+
+```bash
+curl -i http://localhost:8000/agents
+```
+
+Expected:
+
+```text
+HTTP/1.1 401 Unauthorized
+```
+
+Test with the credential used by Agent Gateway:
+
+```bash
+curl -i \
+  -u 'agent-gateway-test:GatewayBackend-Test-2026!' \
+  http://localhost:8000/agents
+```
+
+Expected:
+
+```text
+HTTP/1.1 200 OK
+```
+
+Test a message directly:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -u 'agent-gateway-test:GatewayBackend-Test-2026!' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel": "web",
+    "agent_id": "telecom_contas",
+    "tenant_id": "default",
+    "payload": {
+      "text": "Quero consultar minha fatura",
+      "session_id": "teste-backend-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "message_id": "msg-001"
+    }
+  }'
+```
+
+---
+
+### Terminal 4 — Agent Gateway
+
+```bash
+cd apps/agent_gateway
+source ../../.venv/bin/activate
+```
+
+Start:
+
+```bash
+uvicorn app.main:app \
+  --host 0.0.0.0 \
+  --port 8010 \
+  --reload \
+  --env-file .env
+```
+
+Test health:
+
+```bash
+curl http://localhost:8010/health
+```
+
+Test a protected endpoint without credentials:
+
+```bash
+curl -i http://localhost:8010/backends
+```
+
+Expected:
+
+```text
+HTTP/1.1 401 Unauthorized
+```
+
+Test with the external credential:
+
+```bash
+curl -i \
+  -u 'tia-test:TiaGateway-Test-2026!' \
+  http://localhost:8010/backends
+```
+
+Expected:
+
+```text
+HTTP/1.1 200 OK
+```
+
+---
+
+### 9. Validate the complete circuit
+
+Force the `contas` backend to prevent the router from selecting a backend that has not been started:
+
+```bash
+curl -X POST http://localhost:8010/gateway/message \
+  -u 'tia-test:TiaGateway-Test-2026!' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel": "web",
+    "backend_id": "contas",
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "session_id": "circuito-basic-001",
+    "payload": {
+      "text": "Quero consultar minha fatura",
+      "session_id": "circuito-basic-001",
+      "user_id": "user-001",
+      "customer_id": "12345",
+      "message_id": "msg-circuito-001"
+    }
+  }'
+```
+
+The expected circuit is:
+
+```text
+curl
+  │ Basic tia-test
+  ▼
+Agent Gateway :8010
+  │ Basic agent-gateway-test
+  ▼
+Agent Backend :8000
+  │ Basic agent-backend-test
+  ▼
+MCP Gateway :8300
+  ▼
+MCP Server :8100 ou :8200
+```
+
+---
+
+### 10. How to prove each authentication hop
+
+Run negative tests on each hop.
+
+### Incorrect external secret
+
+```bash
+curl -i \
+  -u 'tia-test:senha-errada' \
+  http://localhost:8010/backends
+```
+
+Expected result:
+
+```text
+401 Unauthorized
+```
+
+### Incorrect gateway-to-backend secret
+
+Temporarily change this in `apps/agent_gateway/.env`:
+
+```env
+BACKEND_AUTH_SECRET=senha-errada
+```
+
+Restart the Agent Gateway and send a message.
+
+The gateway should return a backend error, normally:
+
+```text
+502 Bad Gateway
+```
+
+The internal error will originate from a:
+
+```text
+401 Unauthorized
+```
+
+from the Agent Backend.
+
+### Incorrect backend-to-MCP secret
+
+Temporarily change:
+
+```env
+MCP_GATEWAY_BASIC_SECRET=senha-errada
+```
+
+Restart the backend and execute a phrase that triggers an MCP tool.
+
+The backend should record a failure in the MCP Gateway call with:
+
+```text
+401 Unauthorized
+```
+
+---
+
+### 11. Quick port verification
+
+On Linux or WSL:
+
+```bash
+ss -lntp | grep -E ':8000|:8010|:8100|:8200|:8300'
+```
+
+On Windows PowerShell:
+
+```powershell
+Get-NetTCPConnection -State Listen |
+  Where-Object LocalPort -in 8000,8010,8100,8200,8300 |
+  Sort-Object LocalPort
+```
+
+You should see:
+
+```text
+8000  Agent Backend
+8010  Agent Gateway
+8100  Telecom MCP Server
+8200  Retail MCP Server
+8300  MCP Gateway
+```
+
+### Important note
+
+The original secret must exist in the client component:
+
+```text
+TIA ou curl:
+  TiaGateway-Test-2026!
+
+Agent Gateway:
+  GatewayBackend-Test-2026!
+
+Agent Backend:
+  BackendMcp-Test-2026!
+```
+
+Server components store only the hashes:
+
+```text
+Agent Gateway:
+  hash de TiaGateway-Test-2026!
+
+Agent Backend:
+  hash de GatewayBackend-Test-2026!
+
+MCP Gateway:
+  hash de BackendMcp-Test-2026!
+```
+
+In production, original secrets and hashes should come from Vault or Kubernetes Secret, not `.env` files.
+
+### MCP catalog discovery and synchronization
+
+> Content consolidated from `docs/MCP_GATEWAY_DISCOVERY.md`.
 
 ### Goal
 
@@ -259,903 +2085,382 @@ curl -s -X POST http://localhost:8300/v1/tools/buscar_notas_por_criterios/invoke
   }' | jq
 ```
 
-### Agent Gateway specification
+### MCP Gateway operational runbook
 
-> Consolidated from `specs/SPEC-003-Agent-Gateway.md`.
+> Content consolidated from `Documentacao/MCP_GATEWAY_RUNBOOK.md`.
 
-### Escopo
+### Corrected architecture
 
-O Agent Gateway é o ponto único de entrada da plataforma para canais e consumidores externos.
-
-Sua responsabilidade é receber mensagens, gerenciar sessões globais, resolver o backend/agente responsável, executar roteamento, realizar handoff entre agentes/backends e encaminhar eventos SSE.
-
-O Agent Gateway não executa inferência LLM nem embeddings. Essas capacidades pertencem ao Runtime e ao Agent Framework.
-
----
-
-### Responsabilidades
-
-### Entrada Única da Plataforma
+The backend/agent must not call the final MCP servers directly. The correct flow is:
 
 ```text
-Web
-WhatsApp
-Voice
-Teams
-Slack
-      |
-      v
-Agent Gateway
-      |
-      +--> Agent Backend A
-      |
-      +--> Agent Backend B
-      |
-      +--> Agent Backend C
+agent_template_backend / agent_framework
+  -> MCP Gateway Client
+  -> apps/mcp_gateway
+  -> mcp/servers/telecom_mcp_server ou mcp/servers/retail_mcp_server
 ```
 
-### Gerenciamento de Sessões
+### Start locally
 
-Responsável por:
+From the project root:
 
-- Criação de sessões
-- Recuperação de sessões
-- Atualização de contexto global
-- Persistência de metadados de sessão
-- Correlação de requisições
-
-Exemplo:
-
-```json
-{
-  "session_id": "default:telecom_contas:123",
-  "tenant_id": "default",
-  "active_backend": "telecom_contas",
-  "active_agent": "telecom_contas",
-  "turn_count": 12,
-  "metadata": {}
-}
-```
-
----
-
-### Backend Routing
-
-Resolve qual backend deve processar a mensagem.
-
-Exemplo:
-
-```yaml
-backends:
-  telecom_contas:
-    url: http://backend-contas:8000
-
-  telecom_ofertas:
-    url: http://backend-ofertas:8000
-```
-
-Critérios possíveis:
-
-- Backend padrão
-- Regras YAML
-- Intenção detectada
-- Contexto da sessão
-- Router LLM (opcional)
-
----
-
-### Handoff
-
-Permite transferência entre agentes ou backends.
-
-Exemplo:
-
-```text
-Contas
-   |
-   +--> Ofertas
-   |
-   +--> Retenção
-```
-
-O handoff deve preservar:
-
-- session_id
-- conversation_key
-- business context
-- histórico da conversa
-- metadados de correlação
-
----
-
-### SSE Proxy
-
-Responsável por encaminhar eventos de streaming para clientes.
-
-### Endpoints
-
-| Método | Endpoint |
-|----------|----------|
-| POST | /gateway/message |
-| POST | /gateway/message/sse |
-| GET | /gateway/events/{session_id} |
-
-Eventos SSE suportados:
-
-- connected
-- workflow.started
-- message.responded
-- workflow.completed
-- flow.end
-- error
-
----
-
-### Backend Discovery
-
-Pode operar com catálogo estático ou descoberta dinâmica.
-
-### Catálogo Estático
-
-```yaml
-backends:
-  telecom_contas:
-    url: http://contas:8000
-
-  telecom_ofertas:
-    url: http://ofertas:8000
-```
-
-### Descoberta Dinâmica
-
-```yaml
-service_discovery:
-  enabled: true
-```
-
-Capacidades:
-
-- Registro automático
-- Health check periódico
-- Atualização de catálogo
-- Sincronização de metadados
-
----
-
-### Health e Operação
-
-### Endpoints
-
-| Método | Endpoint |
-|----------|----------|
-| GET | /health |
-| GET | /ready |
-| GET | /backends |
-| GET | /debug/sessions |
-
----
-
-### Contrato GatewayRequest
-
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "session_id": "default:telecom_contas:123",
-  "message": "Quero consultar minha fatura",
-  "business_context": {
-    "customer_key": "11999999999"
-  },
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
-```
-
----
-
-### Contrato GatewayResponse
-
-```json
-{
-  "session_id": "default:telecom_contas:123",
-  "backend": "telecom_contas",
-  "agent": "telecom_contas",
-  "message": "Sua fatura está disponível.",
-  "metadata": {
-    "request_id": "req-001"
-  }
-}
-```
-
----
-
-### Eventos
-
-| Evento | Descrição |
-|----------|----------|
-| agent.gateway.request.received | Requisição recebida |
-| agent.gateway.session.created | Sessão criada |
-| agent.gateway.backend.selected | Backend selecionado |
-| agent.gateway.handoff.started | Handoff iniciado |
-| agent.gateway.handoff.completed | Handoff concluído |
-| agent.gateway.sse.connected | Cliente SSE conectado |
-| agent.gateway.request.failed | Falha de processamento |
-
----
-
-### Métricas
-
-| Métrica | Dimensões |
-|----------|----------|
-| gateway_requests_total | tenant, backend, agent, status |
-| gateway_sessions_active | tenant |
-| gateway_backend_selection_total | backend |
-| gateway_handoff_total | origem, destino |
-| gateway_latency_ms | backend |
-| gateway_sse_connections | backend |
-
----
-
-### Segurança
-
-- Autenticação obrigatória quando configurada.
-- Propagação de identidade entre gateways.
-- Máscara de dados sensíveis em logs.
-- Correlação por request_id, trace_id e session_id.
-- Controle de acesso por tenant.
-
----
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|----------|----------|
-| Disponibilidade | Expor /health e /ready |
-| Escalabilidade | Stateless com escala horizontal |
-| Observabilidade | Logs, métricas e traces |
-| Auditabilidade | Todas as decisões de roteamento rastreáveis |
-| Segurança | Segredos externos e mascaramento |
-| Portabilidade | Local, Docker e Kubernetes |
-| Configuração | YAML e variáveis de ambiente |
-
----
-
-### Critérios de Aceite
-
-- [ ] Recebe mensagens de múltiplos canais.
-- [ ] Seleciona backend corretamente.
-- [ ] Mantém sessão global.
-- [ ] Encaminha SSE.
-- [ ] Executa handoff.
-- [ ] Preserva Business Context.
-- [ ] Suporta múltiplos backends.
-- [ ] Permite descoberta dinâmica.
-- [ ] Expõe health e readiness.
-- [ ] Gera métricas e telemetria.
-
-### MCP Gateway specification
-
-> Consolidated from `specs/SPEC-004-MCP-Gateway.md`.
-
-### Escopo
-
-O MCP Gateway centraliza catálogo, autorização, roteamento, execução, cache, timeout, retry, observabilidade e resposta padronizada de tools MCP.
-
-### Endpoints
-
-| Método | Endpoint | Descrição |
-|---|---|---|
-| `GET` | `/health` | Health check. |
-| `GET` | `/ready` | Readiness check. |
-| `GET` | `/v1/tools` | Catálogo de tools. |
-| `GET` | `/v1/tools/{tool_name}` | Detalhe da tool. |
-| `POST` | `/v1/tools/{tool_name}/invoke` | Execução de tool. |
-| `GET` | `/v1/servers` | Lista MCP servers. |
-
-### ToolInvocation
-
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "tool_name": "consultar_fatura",
-  "arguments": {
-    "msisdn": "11999999999",
-    "invoice_id": "3000131180",
-    "session_id": "default:telecom_contas:session-001"
-  },
-  "business_context": {
-    "customer_key": "11999999999",
-    "contract_key": "3000131180",
-    "session_key": "session-001"
-  },
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
-```
-
-### ToolResult
-
-```json
-{
-  "tool_name": "consultar_fatura",
-  "ok": true,
-  "data": {
-    "invoice_id": "3000131180",
-    "valor_total": 249.90,
-    "vencimento": "2026-06-10",
-    "status": "ABERTA"
-  },
-  "cache": {
-    "hit": false,
-    "ttl_seconds": 300
-  },
-  "latency_ms": 140,
-  "metadata": {
-    "server": "telecom"
-  }
-}
-```
-
-### mcp_servers.yaml
-
-```yaml
-servers:
-  telecom:
-    transport: http
-    url: http://telecom-mcp:8001/mcp
-    enabled: true
-    timeout_seconds: 30
-
-  retail:
-    transport: http
-    url: http://retail-mcp:8002/mcp
-    enabled: true
-    timeout_seconds: 30
-```
-
-### tools.yaml
-
-```yaml
-tools:
-  consultar_fatura:
-    server: telecom
-    enabled: true
-    idempotent: true
-    cache_ttl_seconds: 300
-    allowed_agents:
-      - telecom_contas
-    required_business_keys:
-      - customer_key
-      - contract_key
-
-  solicitar_devolucao:
-    server: retail
-    enabled: true
-    idempotent: false
-    requires_confirmation: true
-    allowed_agents:
-      - retail_orders
-```
-
-### mcp_parameter_mapping.yaml
-
-```yaml
-tools:
-  consultar_fatura:
-    map:
-      customer_key: msisdn
-      contract_key: invoice_id
-      interaction_key: ura_call_id
-      session_key: session_id
-```
-
-### Autorização
-
-```yaml
-authorization:
-  default_policy: deny
-  agents:
-    telecom_contas:
-      allowed_tools:
-        - consultar_fatura
-        - consultar_pagamentos
-        - consultar_plano
-```
-
-### Cache
-
-| Regra | Valor |
-|---|---|
-| Chave | `tenant_id:agent_id:tool_name:hash(arguments)` |
-| Aplicação | Apenas tools idempotentes |
-| Bypass | `metadata.cache_bypass=true` |
-| TTL | `cache_ttl_seconds` |
-| Escrita | Não cachear operações mutáveis |
-
-### Retry e Timeout
-
-```yaml
-execution:
-  default_timeout_seconds: 30
-  retry:
-    enabled: true
-    max_attempts: 2
-    backoff_ms: 250
-  circuit_breaker:
-    enabled: true
-    failure_threshold: 5
-    recovery_seconds: 60
-```
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `mcp.tool.requested` | Tool requisitada. |
-| `mcp.tool.authorized` | Autorização aprovada. |
-| `mcp.tool.denied` | Autorização negada. |
-| `mcp.tool.started` | Execução iniciada. |
-| `mcp.tool.completed` | Execução concluída. |
-| `mcp.tool.failed` | Execução falhou. |
-| `mcp.cache.hit` | Cache hit. |
-| `mcp.cache.miss` | Cache miss. |
-
-### Métricas
-
-| Métrica | Dimensões |
-|---|---|
-| `mcp_tool_calls_total` | tool, server, tenant, agent, status |
-| `mcp_tool_latency_ms` | tool, server |
-| `mcp_tool_errors_total` | tool, server, error_type |
-| `mcp_cache_hits_total` | tool |
-| `mcp_cache_misses_total` | tool |
-
-### Segurança
-
-- Tools são negadas por padrão.
-- Argumentos sensíveis são mascarados.
-- Tools mutáveis exigem confirmação quando configurado.
-- MCP servers não recebem payload bruto de canal.
-- Credenciais de backend são mantidas nos MCP servers ou secret store.
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Catálogo de tools retorna tools habilitadas.
-- [ ] ToolInvocation é validado antes da execução.
-- [ ] Autorização por agente é aplicada.
-- [ ] Parâmetros são derivados do BusinessContext.
-- [ ] Cache só é aplicado a tools idempotentes.
-- [ ] Timeout/retry/circuit breaker são configuráveis.
-- [ ] Eventos e métricas são emitidos.
-- [ ] Falhas retornam ToolResult padronizado.
-- [ ] MCP servers são substituíveis por configuração.
-- [ ] Tools críticas possuem testes de contrato.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Política mínima de operação
-
-Antes de encaminhar uma tool, o runtime deve aplicar a política opcional do backend em `config/tool_policies.yaml`. Os tipos canônicos são `read_only` e `transactional`; esta última pode exigir confirmação booleana explícita e campos obrigatórios. A ausência do arquivo não é erro e preserva os campos legados de `tools.yaml`. A política conversacional não substitui autenticação, autorização, idempotência nem atomicidade no MCP Server.
-
-### Security and identity model
-
-> Consolidated from `specs/SPEC-018-Security-and-Identity-Model.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Security and Identity Model define como workloads autenticam, como componentes autorizam ações, como segredos são protegidos e como dados sensíveis são tratados.
-
-### 2. Modelos de autenticação
-
-| Modo | Uso |
-| --- | --- |
-| config_file | Desenvolvimento local com ~/.oci/config. |
-| instance_principal | Execução em OCI Compute. |
-| workload_identity | Execução em OKE/Kubernetes. |
-| resource_principal | Recursos OCI gerenciados. |
-| api_key | Endpoints compatíveis com OpenAI quando aplicável. |
-
-
-### 3. Workload Identity
-
-Fluxo:
-
-```mermaid
-flowchart LR
-    Pod[Pod Kubernetes] --> SA[ServiceAccount]
-    SA --> WI[Workload Identity]
-    WI --> IAM[OCI IAM Policy]
-    IAM --> Resource[OCI Resource]
-```
-
-### 4. Autorização
-
-Escopos:
-
-- agente pode chamar tool?
-- tenant pode usar provider?
-- canal pode chamar agent_id?
-- usuário pode executar ação?
-- tool mutável exige confirmação?
-
-### 5. Secrets
-
-Secrets não ficam no código.
-
-Fontes:
-
-- OCI Vault;
-- Kubernetes Secrets;
-- secret manager corporativo.
-
-Exemplos:
-
-```text
-LANGFUSE_SECRET_KEY
-OCI_GENAI_API_KEY
-ADB_PASSWORD
-MCP_BACKEND_TOKEN
-```
-
-### 6. Proteção de dados
-
-Aplicar:
-
-- máscara de PII;
-- minimização de metadata;
-- sanitização de payload;
-- não logar secrets;
-- retenção controlada;
-- classificação de dados.
-
-### 7. Segurança em MCP
-
-MCP tools devem ter:
-
-- autorização por agente;
-- allowlist;
-- timeout;
-- retry;
-- idempotência declarada;
-- confirmação para operações mutáveis.
-
-### 8. Segurança em canais
-
-Channel Gateway deve:
-
-- validar assinatura;
-- validar origem;
-- deduplicar;
-- rate limit;
-- remover tokens;
-- normalizar payload;
-- rejeitar anexos inválidos.
-
-### 9. Auditoria
-
-Registrar:
-
-- usuário/canal;
-- agent_id;
-- tenant_id;
-- tool chamada;
-- modelo usado;
-- decisão de guardrail;
-- judge score;
-- erro;
-- trace_id.
-
-### 10. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Secret em .env versionado | Vazamento. | Usar Vault/Secrets. |
-| Tool sem autorização | Acesso indevido. | Allowed agents por tool. |
-| Payload bruto em logs | Exposição de dados. | Mascarar/minimizar. |
-| Instance principal local | Timeout/autenticação inválida. | Usar config_file local. |
-
-
-### 11. Critérios de aceite
-
-- [ ] Modo de autenticação definido por ambiente.
-- [ ] Secrets externos ao código.
-- [ ] MCP tools autorizadas por agente.
-- [ ] Channel Gateway valida origem.
-- [ ] PII mascarada em logs.
-- [ ] Eventos auditáveis emitidos.
-- [ ] Workload Identity definido para OKE.
-- [ ] Security review executado antes de produção.
-
-### Deployment requirements
-
-> Consolidated from `specs/SPEC-008-Deployment.md`.
-
-### Escopo
-
-Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, autenticação OCI, health checks, rollback e operação dos componentes.
-
-### Componentes Deployáveis
-
-| Componente | Artefato |
-|---|---|
-| Agent Gateway | Docker image + Kubernetes Deployment |
-| Channel Gateway | Docker image + Kubernetes Deployment |
-| AI Gateway | Docker image + Kubernetes Deployment |
-| MCP Gateway | Docker image + Kubernetes Deployment |
-| Agent Backend | Docker image + Kubernetes Deployment |
-| MCP Server | Docker image + Kubernetes Deployment |
-| Evaluator API | Docker image + Kubernetes Deployment |
-| Evaluator Batch | Kubernetes CronJob |
-| Frontend Demo | Docker image opcional |
-
-### Pipeline
-
-```mermaid
-flowchart LR
-    A[Commit] --> B[Lint]
-    B --> C[Type Check]
-    C --> D[Unit Tests]
-    D --> E[Contract Tests]
-    E --> F[Security Scan]
-    F --> G[Build Wheel]
-    G --> H[Build Images]
-    H --> I[Publish]
-    I --> J[Deploy Dev]
-    J --> K[Smoke Tests]
-    K --> L[Certification]
-    L --> M[Deploy HML/Prod]
-```
-
-### Stages
-
-```yaml
-stages:
-  - validate
-  - lint
-  - type_check
-  - unit_test
-  - contract_test
-  - security_scan
-  - build_package
-  - build_image
-  - publish
-  - deploy_dev
-  - smoke_test
-  - certification
-  - deploy_hml
-  - deploy_prod
-```
-
-### Kubernetes Deployment
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: agent-runtime
-  labels:
-    app: agent-runtime
-    component: runtime
-spec:
-  replicas: 2
-  selector:
-    matchLabels:
-      app: agent-runtime
-  template:
-    metadata:
-      labels:
-        app: agent-runtime
-    spec:
-      serviceAccountName: agent-runtime-sa
-      containers:
-        - name: agent-runtime
-          image: registry/agent-runtime:1.0.0
-          ports:
-            - containerPort: 8000
-          envFrom:
-            - configMapRef:
-                name: agent-runtime-config
-            - secretRef:
-                name: agent-runtime-secrets
-          readinessProbe:
-            httpGet:
-              path: /ready
-              port: 8000
-          livenessProbe:
-            httpGet:
-              path: /health
-              port: 8000
-```
-
-### Service
-
-```yaml
-apiVersion: v1
-kind: Service
-metadata:
-  name: agent-runtime
-spec:
-  selector:
-    app: agent-runtime
-  ports:
-    - port: 8000
-      targetPort: 8000
-```
-
-### OCI Authentication
-
-| Ambiente | Modo |
-|---|---|
-| Local | `config_file` |
-| Local com endpoint OpenAI-Compatible | API key |
-| OCI Compute | `instance_principal` |
-| OKE | `workload_identity` ou `resource_principal` |
-| Testes | `mock` |
-
-### Variáveis
-
-```env
-LLM_PROVIDER=oci_sdk
-OCI_AUTH_MODE=workload_identity
-ENABLE_LANGFUSE=true
-ENABLE_OTEL=true
-SESSION_REPOSITORY_PROVIDER=autonomous
-MEMORY_REPOSITORY_PROVIDER=autonomous
-CHECKPOINT_REPOSITORY_PROVIDER=autonomous
-```
-
-### Secrets
-
-| Secret | Uso |
-|---|---|
-| `LANGFUSE_PUBLIC_KEY` | Langfuse |
-| `LANGFUSE_SECRET_KEY` | Langfuse |
-| `OCI_GENAI_API_KEY` | OCI OpenAI-Compatible |
-| `ADB_PASSWORD` | Autonomous Database |
-| `MCP_BACKEND_TOKEN` | Integrações MCP |
-| `OTEL_AUTH_TOKEN` | Exportador OTEL, se aplicável |
-
-### Health Checks
-
-| Endpoint | Uso |
-|---|---|
-| `/health` | Processo vivo. |
-| `/ready` | Pronto para tráfego. |
-| `/version` | Versão de build. |
-| `/debug/env` | Ambiente sem segredos, quando habilitado. |
-
-### Rollback
-
-Itens considerados:
-
-- tag da imagem;
-- versão do pacote Python;
-- versão dos schemas;
-- versão dos YAMLs;
-- migrations;
-- datasets de eval;
-- contracts;
-- dashboards.
-
-### Smoke Tests
+### Terminal 1 - Telecom MCP Server
 
 ```bash
-curl -f http://agent-runtime:8000/health
-curl -f http://agent-gateway:9000/health
-curl -f http://mcp-gateway:8300/health
-curl -f http://ai-gateway:9100/health
+cd mcp/servers/telecom_mcp_server
+python -m uvicorn main:app --host 0.0.0.0 --port 8100 --reload
 ```
 
-### Certification Stage
+### Terminal 2 - Retail MCP Server
 
-A pipeline executa:
+```bash
+cd mcp/servers/retail_mcp_server
+python -m uvicorn main:app --host 0.0.0.0 --port 8200 --reload
+```
 
-- health checks;
-- contrato GatewayRequest;
-- roteamento;
-- MCP invoke;
-- LLM mock/real conforme ambiente;
-- guardrails;
-- judges;
-- memória/checkpoint;
-- relatório JSON/HTML.
+### Terminal 3 - MCP Gateway
 
+```bash
+cd apps/mcp_gateway
+export MCP_GATEWAY_CONFIG_PATH=config/mcp_gateway.yaml
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8300 --reload
+```
 
-### Requisitos Não Funcionais
+### Terminal 4 - Backend/agent
 
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+In the `.env` of the backend/agent or runtime that uses `agent_framework`, enable:
 
+```env
+ENABLE_MCP_TOOLS=true
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_AGENT_ID=telecom_contas
+MCP_GATEWAY_TENANT_ID=default
+```
 
-### Critérios de Aceite
+### Quick tests
 
-- [ ] Cada app possui Dockerfile.
-- [ ] Cada app possui manifest Kubernetes.
-- [ ] CI executa lint, type check e testes.
-- [ ] Contract tests validam contratos principais.
-- [ ] Security scan executa antes do publish.
-- [ ] Secrets não são versionados.
-- [ ] Workload Identity está configurado em OKE.
-- [ ] Health/readiness/liveness estão ativos.
-- [ ] Smoke tests rodam após deploy.
-- [ ] Rollback está documentado.
+### Gateway health
 
+```bash
+curl http://localhost:8300/health
+```
 
-### Glossário
+### List of tools exposed by the gateway
 
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
+```bash
+curl http://localhost:8300/v1/tools
+```
+
+### Tool call through the gateway
+
+```bash
+curl -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "channel": "web",
+    "tool_name": "consultar_fatura",
+    "arguments": {
+      "msisdn": "11999999999",
+      "invoice_id": "INV-123"
+    },
+    "business_context": {},
+    "metadata": {"session_id": "local-test"}
+  }'
+```
+
+Expected response: `ok: true`, `data.invoice_id`, `data.msisdn`, `metadata.server: telecom`.
+
+### What was fixed
+
+- `apps/mcp_gateway/config/mcp_gateway.yaml` now points to the real MCP servers on ports `8100` and `8200`.
+- MCP Gateway now supports the legacy MCP-server contract: `POST /mcp/tools/call` with `{tool_name, arguments}`.
+- `agent_framework` gained the flags `MCP_GATEWAY_ENABLED`, `MCP_GATEWAY_URL`, `MCP_GATEWAY_TOKEN`, `MCP_GATEWAY_AGENT_ID`, and `MCP_GATEWAY_TENANT_ID`.
+- `MCPToolRouter` now calls the MCP Gateway when `MCP_GATEWAY_ENABLED=true`.
+- `libs/agent_framework/config/mcp_servers.yaml` was retained as a logical registry/fallback, not as the primary path when the gateway is active.
+
+### Architectural evolution of the gateways
+
+> Content consolidated from `Documentacao/README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md`.
+
+This overlay removes the concept of a separate `AI Gateway`.
+
+### Architecture
+
+```text
+Frontend
+  ↓
+Agent Gateway
+  ├── governance
+  ├── model policies
+  ├── rate limit
+  ├── audit
+  └── evaluation hooks
+  ↓
+Agent Backend / Runtime
+  ├── LangGraph
+  ├── state
+  ├── memory
+  ├── checkpoints
+  └── LLM providers via profiles existentes
+       ↓
+     MCP Gateway
+       ↓
+     MCP Servers
+```
+
+### What belongs in the Agent Gateway
+
+```text
+apps/agent_gateway/app/governance/
+apps/agent_gateway/app/governance_middleware.py
+apps/agent_gateway/app/routes/governed_proxy_example.py
+apps/agent_gateway/config/gateway_governance.yaml
+```
+
+### What belongs in the MCP Gateway
+
+```text
+apps/mcp_gateway/
+libs/agent_framework/src/agent_framework/gateways/mcp_gateway_client.py
+libs/agent_framework/src/agent_framework/runtime_mcp_gateway_adapter.py
+```
+
+### Apply overlay
+
+```bash
+unzip agent_platform_agent_gateway_mcp_gateway_overlay.zip -d /tmp/overlay
+rsync -av /tmp/overlay/ ./
+```
+
+### Start MCP Gateway locally
+
+```bash
+docker compose -f deploy/docker/docker-compose.mcp-gateway.yml up --build
+```
+
+Services:
+
+```text
+MCP Gateway      http://localhost:8300
+Mock Telecom MCP http://localhost:8001
+```
+
+### Test MCP Gateway
+
+```bash
+curl http://localhost:8300/health
+curl http://localhost:8300/v1/tools
+```
+
+Execute tool:
+
+```bash
+curl -s -X POST http://localhost:8300/v1/tools/consultar_fatura/invoke \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tenant_id": "default",
+    "agent_id": "telecom_contas",
+    "channel": "web",
+    "tool_name": "consultar_fatura",
+    "business_context": {
+      "customer_key": "11999999999",
+      "contract_key": "INV-001",
+      "session_key": "session-001"
+    }
+  }' | jq
+```
+
+### How to plug it into Agent Gateway
+
+In the actual `POST /gateway/message` handler, before forwarding to backend/runtime:
+
+```python
+governed_body, headers = governance.prepare_backend_request(body)
+```
+
+After receiving the backend response:
+
+```python
+return governance.process_backend_response(data)
+```
+
+The file below shows a complete example:
+
+```text
+apps/agent_gateway/app/routes/governed_proxy_example.py
+```
+
+### Runtime Variables
+
+```env
+MCP_GATEWAY_ENABLED=true
+MCP_GATEWAY_URL=http://localhost:8300
+MCP_GATEWAY_TIMEOUT_SECONDS=60
+```
+
+### Important
+
+There is no `apps/ai_gateway`.
+
+Model governance lives in Agent Gateway as policy/metadata.
+
+Runtime continues using the existing LLM providers and may read the policy sent by the Gateway from:
+
+```python
+state["metadata"]["model_policy"]
+```
+
+### File and responsibility inventory
+
+> Content consolidated from `Documentacao/INVENTARIO_AGENT_GATEWAY_MCP_GATEWAY.md`.
+
+This inventory lists the files included in the `agent_platform_agent_gateway_mcp_gateway_overlay.zip` overlay, indicating the area, type of change, and purpose of each file.
+
+### Summary
+
+| Area | Quantity |
+|---|---:|
+| Documentation | 1 |
+| Agent Gateway | 10 |
+| MCP Gateway | 5 |
+| Agent Framework | 4 |
+| Template Backend | 2 |
+| MCP Server Mock | 2 |
+| Deploy | 2 |
+
+### Files by area
+
+### Documentation
+
+| File | Type | Purpose |
+|---|---|---|
+| `README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md` | New / overlay | Main overlay document. Explains the new architecture without a separate AI Gateway, with Agent Gateway governing policies/models and a separate MCP Gateway for tools. |
+
+### Agent Gateway
+
+| File | Type | Purpose |
+|---|---|---|
+| `apps/agent_gateway/app/config/governance_loader.py` | New / overlay | Loads the Agent Gateway governance YAML file from `AGENT_GATEWAY_GOVERNANCE_CONFIG`. |
+| `apps/agent_gateway/app/governance/__init__.py` | New / overlay | Initializes the Agent Gateway governance Python package. |
+| `apps/agent_gateway/app/governance/audit.py` | New / overlay | Centralizes logging/auditing of Agent Gateway governance decisions, with simple protection to avoid logging the full message. |
+| `apps/agent_gateway/app/governance/evaluation_hooks.py` | New / overlay | Hooks before and after the backend/runtime call. Used for sampling, evaluator, scoring, or future Langfuse integration. |
+| `apps/agent_gateway/app/governance/model_policies.py` | New / overlay | Resolves model/profile policies in Agent Gateway. Defines which provider/model/profile should be used by operation, tenant, and agent. |
+| `apps/agent_gateway/app/governance/rate_limit.py` | New / overlay | Implements in-memory rate limiting by tenant, agent, and channel before forwarding the request to backend/runtime. |
+| `apps/agent_gateway/app/governance/usage.py` | New / overlay | Hook to record gateway usage, applied policies, and backend responses. Ready to plug into metrics, database, Langfuse, or OTEL. |
+| `apps/agent_gateway/app/governance_middleware.py` | New / overlay | Main Agent Gateway governance component. Applies rate limiting, resolves `model_policy`, generates headers/metadata, and executes hooks before/after the backend. |
+| `apps/agent_gateway/app/routes/governed_proxy_example.py` | New / overlay | Example governed route demonstrating how to apply governance before forwarding to the Agent Backend/Runtime. |
+| `apps/agent_gateway/config/gateway_governance.yaml` | New / overlay | Agent Gateway governance configuration: profiles, operation profiles, allowed providers, rate limits, propagated headers, and evaluation hooks. |
+
+### MCP Gateway
+
+| File | Type | Purpose |
+|---|---|---|
+| `apps/mcp_gateway/Dockerfile` | New / overlay | MCP Gateway Docker image. |
+| `apps/mcp_gateway/app/__init__.py` | New / overlay | Initializes the MCP Gateway application Python package. |
+| `apps/mcp_gateway/app/main.py` | New / overlay | MCP Gateway FastAPI application. Exposes health, ready, tool catalog, and invoke endpoint with auth, authorization, mapping, cache, timeout, and retry. |
+| `apps/mcp_gateway/config/mcp_gateway.yaml` | New / overlay | Central MCP Gateway configuration: MCP servers, tools, versions, cache, timeout, retry, authorization by agent/channel, and BusinessContext → parameter mapping. |
+| `apps/mcp_gateway/requirements.txt` | New / overlay | MCP Gateway Python dependencies. |
+
+### Agent Framework
+
+| File | Type | Purpose |
+|---|---|---|
+| `libs/agent_framework/src/agent_framework/gateway_policy_context.py` | New / overlay | Framework helper for Runtime to read the model policy sent by Agent Gateway in `state['metadata']['model_policy']`. |
+| `libs/agent_framework/src/agent_framework/gateways/__init__.py` | New / overlay | Initializes the framework gateway-client package, exporting `MCPGatewayClient`. |
+| `libs/agent_framework/src/agent_framework/gateways/mcp_gateway_client.py` | New / overlay | Async framework client for MCP Gateway: list tools and execute tools. |
+| `libs/agent_framework/src/agent_framework/runtime_mcp_gateway_adapter.py` | New / overlay | Optional mixin for agents/runtime to call tools through MCP Gateway and append results to `state['mcp_results']`. |
+
+### Template Backend
+
+| File | Type | Purpose |
+|---|---|---|
+| `templates/agent_template_backend/app/mcp_gateway_client_factory.py` | New / overlay | Factory in the template backend to build `MCPGatewayClient` from environment variables. |
+
+### MCP Server Mock
+
+| File | Type | Purpose |
+|---|---|---|
+| `mcp/servers/mock_telecom_mcp/app.py` | New / overlay | Mock MCP Server with `consultar_fatura` and `consultar_pagamentos` tools for local MCP Gateway validation. |
+| `mcp/servers/mock_telecom_mcp/requirements.txt` | New / overlay | Dependencies for the telecom mock MCP Server used in local tests. |
+
+### Deploy
+
+| File | Type | Purpose |
+|---|---|---|
+| `deploy/docker/docker-compose.mcp-gateway.yml` | New / overlay | Docker Compose file to start MCP Gateway and `mock_telecom_mcp` locally. |
+| `deploy/k8s/mcp-gateway.yaml` | New / overlay | Kubernetes Deployment and Service manifest for MCP Gateway. |
+
+### Integration notes
+
+### Agent Gateway
+
+The files under `apps/agent_gateway` do not create a new service. They evolve the existing Agent Gateway to act as the platform's dedicated gateway, centralizing:
+
+- model/profile policies;
+- rate limiting;
+- auditing;
+- evaluation hooks;
+- propagation of governance metadata to Runtime.
+
+The `governed_proxy_example.py` route is an integration example. The actual `POST /gateway/message` handler should apply:
+
+```python
+governed_body, headers = governance.prepare_backend_request(body)
+```
+
+before calling backend/runtime, and:
+
+```python
+return governance.process_backend_response(data)
+```
+
+after receiving the response.
+
+### MCP Gateway
+
+MCP Gateway is a separate service. It centralizes:
+
+- tool catalog;
+- authorization by agent/channel;
+- tool versioning;
+- BusinessContext-to-parameter mapping;
+- cache;
+- timeout;
+- retry;
+- simple audit.
+
+### Runtime / Backend
+
+Runtime remains responsible for:
+
+- LangGraph;
+- state;
+- memory;
+- checkpoints;
+- flow;
+- existing LLM providers.
+
+Runtime now calls tools through MCP Gateway using `MCPGatewayClient` and/or `MCPGatewayRuntimeMixin`.
+
+### AI Gateway
+
+This overlay does not create `apps/ai_gateway`. Model governance stays in Agent Gateway, and LLM execution remains in Runtime/backend using the existing providers.
+
+### Source files
+
+The files below were consolidated into this manual:
+
+- `Documentacao/MANUAL_AGENT_PLATFORM_GATEWAYS.md`
+- `Documentacao/MANUAL_EXECUCAO_AGENT_GATEWAY_MCP_GATEWAY_FRONTEND.md`
+- `Documentacao/Implementando_Basic_Auth.md`
+- `docs/MCP_GATEWAY_DISCOVERY.md`
+- `Documentacao/MCP_GATEWAY_RUNBOOK.md`
+- `Documentacao/README_AGENT_GATEWAY_AND_MCP_GATEWAY_EVOLUTION.md`
+- `Documentacao/INVENTARIO_AGENT_GATEWAY_MCP_GATEWAY.md`
+
+### Maintenance rule
+
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md b/docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md
index 1d586bf..7a83179 100644
--- a/docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md
+++ b/docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md
@@ -1,73 +1,102 @@
-
-### Guardrails, Judges and Transaction Evaluation
+### Guardrails, Judges, and Transaction Evaluation
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **native/external guardrails, judges, transactional sampling and grounding**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **native/external guardrails, judges, transactional sampling, and grounding**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Native/external guardrails, judges, transactional sampling and grounding.
+Native/external guardrails, judges, transactional sampling, and grounding.
 
 ### Consolidated technical content
 
-### Guardrails, Judges and Transaction Evaluation
+### Guardrails, Judges, and Transaction Evaluation
 
-This guide explains validation layers and how agent-specific policies extend the framework without introducing domain coupling.
+Manual for input/output guardrails, agent-specific extensions, external judges, mandatory execution on transactions, and the signals/evidence used during evaluation.
 
-### Guardrail stages
+### How to use this document
 
-Input guardrails validate/sanitize/block user input before domain execution. Output guardrails validate the produced response before it leaves the runtime. Optional rails can be enabled according to agent/environment policy.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### Agent-owned extensions
+### Guardrails implemented in the framework
 
-The framework exposes an SPI/configuration model for external guardrails and judges. An agent points configuration to implementation classes in its own package. The shared framework must not import concrete telecom, retail or company validation modules.
+> Content consolidated from `Documentacao/README_GUARDRAILS_IMPLEMENTADOS.md`.
 
-Synchronous validators may execute in worker threads; asynchronous validators execute on the event loop. Independent judges may execute concurrently to reduce latency while the configured logical result order is preserved.
+This version adds a pragmatic guardrail layer to `agent_framework`, inspired by separating rails by stage: input, output, retrieval, and execution/tool.
 
-### Transactional judge sampling
+### Input rails
 
-Normal evaluation may use sampling, but transactional interactions can be configured with `always_run_for_transactional`. Transaction detection occurs before applying `sample_rate` so critical side-effecting paths are not randomly skipped.
+- `MSIZE` — blocks excessively large messages.
+- `MSK` — masks CPF, CNPJ, phone, e-mail, card, postal code, RG, tokens, and keys.
+- `TOX` — detects toxicity and records severity without blocking by default.
+- `PINJ` — detects prompt injection and records a score.
+- `JBRK` — detects jailbreak/bypass roleplay and records a score.
+- `VLOOP` — blocks repetitive conversational loops.
 
-Signals may include transaction lifecycle state, required/received confirmation, selected or pending tool call, tool-policy result and MCP execution results. Detection intentionally uses multiple signals instead of depending on a single field.
+### Output rails
 
-### Operational evidence
+- `PII_OUT` — masks PII in the agent response.
+- `CMP` — softens absolute promises and excessive guarantee language.
+- `REVPREC` — blocks verbalization of an operational action without tool confirmation.
+- `GND` — signals grounding/risk when there is a specific answer without evidence.
+- `ALUC_RISK` — marks hallucination risk for telemetry and judges.
 
-Judges must distinguish a model claim from an executed action. MCP results and transaction evidence provide grounding for assertions such as cancellation, credit, update or protocol creation.
+### Optional rails
 
-### Compatibility
+- `RET_REL` — validates retrieval-chunk relevance using a minimum score.
+- `TOOL_VAL` — validates MCP/tool name, required arguments, negative values, and allowlist.
 
-Legacy validators may use temporary compatibility shims during migration, but new code should depend on the external SPI/configuration. Native framework guardrails continue to coexist with agent-specific policies.
+### Files changed
 
-### Testing
+- `agent_framework/src/agent_framework/guardrails/rails.py`
+- `agent_framework/src/agent_framework/guardrails/pipeline.py`
+- `agent_framework/src/agent_framework/guardrails/__init__.py`
 
-Test allow/sanitize/block behavior, exceptions/fail-closed behavior where configured, sync/async external validators, judge concurrency, transactional sample-rate bypass, MCP evidence propagation and isolation between two agents with different policies.
+### Quick use
 
-### Source material consolidated
+```python
+from agent_framework.guardrails.pipeline import GuardrailPipeline
 
-- `Documentacao/README_GUARDRAILS_IMPLEMENTADOS.md`
-- `docs/EXTERNAL_GUARDRAILS_JUDGES.md`
-- `docs/JUDGES_TRANSACTIONAL_SAMPLING_FIX.md`
-- Global Supervisor and guardrail validation records under `docs/`
+pipeline = GuardrailPipeline()
 
-### Detailed normative and implementation reference
+sanitized_input, input_decisions = await pipeline.run_input(
+    user_text,
+    {"history_texts": history_texts},
+)
 
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
+final_answer, output_decisions = await pipeline.run_output(
+    answer,
+    context,
+)
+```
 
-### External guardrails and judges SPI
+For tools/MCP:
 
-> Consolidated from `docs/EXTERNAL_GUARDRAILS_JUDGES.md`.
+```python
+_, decisions = await pipeline.run_tool(
+    "cancelar_produto",
+    {"produto": "VAS", "valor": 0},
+    {
+        "required_args": ["produto"],
+        "allowed_tools": ["cancelar_produto", "consultar_fatura"],
+    },
+)
+```
+
+### SPI for external guardrails and judges
+
+> Content consolidated from `docs/EXTERNAL_GUARDRAILS_JUDGES.md`.
 
 `agent_framework_oci` supports agent-owned guardrails and judges without importing domain code into the core.
 
@@ -88,602 +117,107 @@ judges:
 
 Native entries remain unchanged. External synchronous `evaluate()` methods execute in worker threads via `asyncio.to_thread`; asynchronous methods execute concurrently on the framework event loop. Judges run concurrently with `asyncio.gather`, preserving YAML result order. Agent plugins should reuse the LLM supplied by the framework rather than instantiate a separate provider.
 
-The core must not reference a concrete agent package, company, product, telecom identifier or domain-specific policy. Domain-specific variants belong to the agent and should receive distinct public codes/names.
+The core must not reference a concrete agent package, company, product, telecom identifier, or domain-specific policy. Domain-specific variants belong to the agent and should receive distinct public codes/names.
 
 ### Compatibility rule
+
 Domain policies must not be replaced by cosmetically generic text inside the core while losing the original policy. The generic core implementation and the agent-specific implementation may coexist; the embedding agent explicitly selects its own code/name in YAML.
 
 Legacy business validators should migrate to the agent domain. A temporary compatibility shim is acceptable for old imports, but new application code must import the agent-owned implementation.
 
-### Guardrails specification
+### Mandatory judge execution for transactions
 
-> Consolidated from `specs/SPEC-005-Guardrails.md`.
+> Content consolidated from `docs/JUDGES_TRANSACTIONAL_SAMPLING_FIX.md`.
 
-### Escopo
+### Problem
 
-Guardrails são políticas executadas sobre entrada, saída, tool calls, RAG e respostas finais. A plataforma suporta guardrails globais, por agente, por canal e por fase.
+Even with `always_run_for_transactional: true`, judges could be skipped by sampling because the `judge` node sent only `context`, `route`, `intent`, and `mcp_results`. Transactional fields produced by the runtime did not reach `JudgePipeline`.
 
-### Fases
+### Fix
 
-| Fase | Entrada | Saída |
-|---|---|---|
-| Input | `user_text`, `context` | `sanitized_input`, `GuardrailResult` |
-| Tool | `ToolInvocation` | tool permitida/bloqueada |
-| RAG | query/contexto recuperado | contexto aprovado/filtrado |
-| Output | `response_text` | resposta aprovada/sanitizada/bloqueada |
-| Review | resposta + evidências | decisão final |
+The `judge` node now passes:
 
-### GuardrailResult
+- `transaction_status`
+- `confirmation_required`
+- `confirmation_received`
+- `tool_policy_result`
+- `selected_tool_call`
+- `pending_tool_call`
+- `mcp_results` as evidence
 
-```json
-{
-  "code": "PINJ",
-  "phase": "input",
-  "status": "blocked",
-  "severity": "high",
-  "score": 0.98,
-  "message": "Entrada bloqueada por política.",
-  "details": {
-    "matched_policy": "prompt_injection"
-  }
-}
-```
+`JudgePipeline` detects transactions through multiple signals and evaluates `always_run_for_transactional` before applying `sample_rate`.
 
-### Configuração Global
+With the configuration below, common queries continue to be sampled at 25%, but `AWAITING_CONFIRMATION`, `COMPLETED`, `FAILED`, or `CANCELLED` turns always run the judges.
 
 ```yaml
-input:
-  - code: MSK
-    enabled: true
-    mode: enforce
-  - code: VLOOP
-    enabled: true
-    mode: enforce
-  - code: PINJ
-    enabled: true
-    mode: enforce
-
-output:
-  - code: REVPREC
-    enabled: true
-    mode: enforce
-  - code: DLEX_OUT
-    enabled: true
-    mode: enforce
-  - code: PINJ
-    enabled: true
-    mode: observe
+enabled: true
+sample_rate: 0.25
+always_run_for_transactional: true
 ```
 
-### Configuração por Agente
+### Global Supervisor validation
 
-```yaml
-agents:
-  telecom_contas:
-    input:
-      - code: BILLING_INPUT_POLICY
-        enabled: true
-        mode: observe
-    output:
-      - code: BILLING_COMPLIANCE
-        enabled: true
-        mode: enforce
-```
+> Content consolidated from `docs/docs_GLOBAL_SUPERVISOR_VALIDATION.txt`.
 
-### Modos
+VALIDATION - GLOBAL SUPERVISOR
 
-| Modo | Comportamento |
-|---|---|
-| `enforce` | Aplica bloqueio, máscara ou alteração. |
-| `observe` | Registra sem bloquear. |
-| `fail_open` | Em erro técnico, prossegue e emite NOC. |
-| `fail_closed` | Em erro técnico, bloqueia. |
+Implemented changes:
 
-### Tipos
+1. Framework
+- agent_framework.global_supervisor.models
+- agent_framework.global_supervisor.config
+- agent_framework.global_supervisor.session_store
+- agent_framework.global_supervisor.router
+- agent_framework.global_supervisor.client
 
-| Tipo | Implementação |
-|---|---|
-| Determinístico | Regex, listas, tamanho, estrutura, regras. |
-| LLM | Classificação semântica por profile. |
-| Híbrido | Determinístico + LLM em casos ambíguos. |
+2. New service
+- agent_gateway/app/main.py
+- agent_gateway/app/settings.py
+- agent_gateway/config/backends.yaml
+- agent_gateway/README.md
+- agent_gateway/Dockerfile
+- agent_gateway/docs/ARQUITETURA_GLOBAL_SUPERVISOR.md
 
-### Profiles LLM
+3. Docker Compose
+- agent-gateway service added on port 8010.
 
-```yaml
-profiles:
-  guardrail:
-    provider: oci_openai
-    model: openai.gpt-4.1
-    temperature: 0
-    max_tokens: 600
+Validations performed:
 
-  grl:
-    provider: oci_openai
-    model: openai.gpt-4.1
-    temperature: 0
-    max_tokens: 700
-```
+- python3 -m compileall -q agent_framework/src/agent_framework/global_supervisor agent_gateway/app
+  Result: OK
 
-### Fluxo
+- Hybrid-routing smoke test:
+  Input 1: "My bill is too high" -> billing
+  Input 2: "and this amount?" on the same session_id -> billing via active_backend
+  Result: OK
 
-```mermaid
-flowchart TD
-    A[Input] --> B[Deterministic Guardrails]
-    B --> C{Blocked?}
-    C -- yes --> D[Safe Response]
-    C -- no --> E[LLM Guardrails]
-    E --> F{Approved?}
-    F -- no --> D
-    F -- yes --> G[Runtime]
-```
+- FastAPI app import smoke test:
+  from app.main import app, registry, router
+  Result: OK
 
-### Eventos
+Note:
+- The gateway SSE proxy was left as a future step. The `/gateway/message/sse` endpoint already routes and forwards as a normal message; for end-to-end SSE, a proxy from `/gateway/events/{session_id}` to the active backend can be implemented.
 
-| Evento | Descrição |
-|---|---|
-| `guardrail.started` | Execução iniciada. |
-| `guardrail.completed` | Execução concluída. |
-| `guardrail.blocked` | Conteúdo bloqueado. |
-| `guardrail.masked` | Conteúdo mascarado. |
-| `guardrail.failed` | Falha técnica. |
-| `guardrail.observe` | Política observacional registrada. |
+### Guardrail event validation
 
-### Códigos Base
+> Content consolidated from `docs/docs_VALIDATION_GUARDRAILS_IC.txt`.
 
-| Código | Fase | Uso |
-|---|---|---|
-| `MSK` | input/output | Mascaramento. |
-| `VLOOP` | input | Detecção de loop. |
-| `PINJ` | input/output | Prompt injection. |
-| `REVPREC` | output | Revisão de precisão. |
-| `DLEX_OUT` | output | Controle de dados e linguagem na saída. |
-| `RAGSEC` | rag/output | Segurança de contexto recuperado. |
+VALIDATION REPORT - guardrails parallel fail-fast + observer IC
+Date: 2026-06-03
 
-### Testes
+compileall: OK
+smoke-tests: OK
 
-| Teste | Objetivo |
-|---|---|
-| Unitário | Validar guardrail isolado. |
-| Config | Validar YAML e schema. |
-| Integração | Validar execução no workflow. |
-| Observabilidade | Validar eventos e traces. |
-| Negativo | Validar bloqueio. |
-| Observe-only | Validar não bloqueio. |
+### Source files
 
+The files below were consolidated into this manual:
 
-### Requisitos Não Funcionais
+- `Documentacao/README_GUARDRAILS_IMPLEMENTADOS.md`
+- `docs/EXTERNAL_GUARDRAILS_JUDGES.md`
+- `docs/JUDGES_TRANSACTIONAL_SAMPLING_FIX.md`
+- `docs/docs_GLOBAL_SUPERVISOR_VALIDATION.txt`
+- `docs/docs_VALIDATION_GUARDRAILS_IC.txt`
 
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
+### Maintenance rule
 
-
-### Critérios de Aceite
-
-- [ ] Guardrails globais são carregados por YAML.
-- [ ] Guardrails por agente sobrescrevem ou complementam globais.
-- [ ] GuardrailResult é gerado para cada execução.
-- [ ] Modo enforce bloqueia quando aplicável.
-- [ ] Modo observe não bloqueia.
-- [ ] Falhas técnicas seguem política configurada.
-- [ ] Guardrails LLM usam profile dedicado.
-- [ ] Eventos e métricas são emitidos.
-- [ ] Testes cobrem casos positivos e negativos.
-- [ ] Output guardrails executam antes da resposta final.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Evaluation specification
-
-> Consolidated from `specs/SPEC-006-Evals.md`.
-
-### Escopo
-
-A camada de Evals executa avaliação online, avaliação offline, regressão, certificação e publicação de métricas. Ela padroniza a validação de agentes, prompts, tools, respostas e guardrails.
-
-### Componentes
-
-| Componente | Responsabilidade |
-|---|---|
-| Online Judges | Avaliação durante a execução. |
-| Offline Evaluator | Avaliação batch de conversas. |
-| Dataset Runner | Execução de datasets versionados. |
-| Regression Runner | Comparação entre versões. |
-| Certification Suite | Validação técnica e funcional. |
-| Metrics Engine | Cálculo de métricas. |
-| Persistence | Persistência de runs e itens. |
-| Exporter | Exportação TXT.GZ/JSON/HTML. |
-| Publisher | Publicação de scores no Langfuse. |
-
-### Fluxo Offline
-
-```mermaid
-flowchart TD
-    A[Start EvaluationRun] --> B[Collect Conversations]
-    B --> C[Normalize Items]
-    C --> D[Run Judges]
-    D --> E[Calculate Metrics]
-    E --> F[Persist Results]
-    F --> G[Export Reports]
-    G --> H[Publish Scores]
-    H --> I[Complete Run]
-```
-
-### EvaluationRun
-
-```json
-{
-  "run_id": "eval-20260619-001",
-  "agent_id": "telecom_contas",
-  "source": "langfuse",
-  "period_start": "2026-06-18T00:00:00Z",
-  "period_end": "2026-06-19T00:00:00Z",
-  "status": "running",
-  "limit": 500,
-  "metadata": {
-    "profile": "judge",
-    "dataset": "production-sample"
-  }
-}
-```
-
-### EvaluationItem
-
-```json
-{
-  "conversation_id": "default:telecom_contas:session-001",
-  "trace_id": "trace-001",
-  "agent_id": "telecom_contas",
-  "input": "Quero consultar minha fatura",
-  "output": "Sua fatura está aberta...",
-  "evidence": {
-    "mcp_results": [],
-    "rag_context": ""
-  },
-  "scores": {
-    "quality": 0.86,
-    "groundedness": 0.78,
-    "safety": 1.0,
-    "resolution": 0.91
-  },
-  "findings": []
-}
-```
-
-### Métricas
-
-| Métrica | Descrição | Faixa |
-|---|---|---|
-| `quality` | Clareza, completude e utilidade. | 0–1 |
-| `groundedness` | Aderência a evidências MCP/RAG. | 0–1 |
-| `safety` | Conformidade de segurança. | 0–1 |
-| `resolution` | Capacidade de resolver a intenção. | 0–1 |
-| `tool_correctness` | Uso correto de tools. | 0–1 |
-| `policy_compliance` | Aderência a regras de domínio. | 0–1 |
-
-### Dataset
-
-```yaml
-dataset:
-  name: telecom_contas_billing
-  version: 1.0.0
-  items:
-    - id: billing-001
-      input: "Quero consultar minha fatura"
-      business_context:
-        customer_key: "11999999999"
-        contract_key: "3000131180"
-      expected:
-        route: billing_agent
-        tools:
-          - consultar_fatura
-        min_scores:
-          quality: 0.75
-          groundedness: 0.70
-          safety: 1.0
-```
-
-### Judges
-
-```yaml
-judges:
-  - name: response_quality
-    enabled: true
-    threshold: 0.7
-    profile: judge
-
-  - name: groundedness
-    enabled: true
-    threshold: 0.6
-    profile: judge
-
-  - name: safety
-    enabled: true
-    threshold: 1.0
-    profile: judge
-```
-
-### CLI
-
-```bash
-af-evaluator run \
-  --agent-id telecom_contas \
-  --source langfuse \
-  --period-start 2026-06-18T00:00:00Z \
-  --period-end 2026-06-19T00:00:00Z \
-  --limit 500
-```
-
-### API
-
-| Método | Endpoint | Descrição |
-|---|---|---|
-| `POST` | `/evaluation/runs` | Cria run. |
-| `GET` | `/evaluation/runs/{run_id}` | Consulta run. |
-| `GET` | `/evaluation/runs/{run_id}/items` | Lista itens. |
-| `POST` | `/evaluation/datasets/{name}/run` | Executa dataset. |
-| `GET` | `/health` | Health check. |
-
-### Persistência
-
-| Tabela | Conteúdo |
-|---|---|
-| `EVAL_RUNS` | Runs executadas. |
-| `EVAL_ITEMS` | Conversas avaliadas. |
-| `EVAL_SCORES` | Scores por métrica. |
-| `EVAL_FINDINGS` | Achados. |
-| `EVAL_EXPORTS` | Arquivos exportados. |
-
-### Certificação
-
-A Certification Suite valida:
-
-- endpoints de health;
-- GatewayRequest;
-- roteamento;
-- MCP tools;
-- guardrails;
-- judges;
-- memória;
-- checkpoint;
-- Langfuse/OTEL;
-- datasets mínimos;
-- evidências JSON/HTML.
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `eval.run.started` | Run iniciada. |
-| `eval.item.completed` | Item avaliado. |
-| `eval.run.completed` | Run concluída. |
-| `eval.run.failed` | Run falhou. |
-| `eval.score.published` | Score publicado. |
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Evaluator executa runs por período/agente.
-- [ ] Langfuse é fonte suportada.
-- [ ] Datasets são versionados.
-- [ ] LLM Judges usam profile `judge`.
-- [ ] Scores são persistidos.
-- [ ] TXT.GZ/JSON/HTML são exportáveis.
-- [ ] Scores podem ser publicados no Langfuse.
-- [ ] Certification Suite gera evidências.
-- [ ] Métricas mínimas são padronizadas.
-- [ ] Falhas permitem retomada por checkpoint de run.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Evaluation and certification framework
-
-> Consolidated from `specs/SPEC-019-Evaluation-and-Certification-Framework.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Evaluation mede qualidade e comportamento. Certification valida prontidão técnica e funcional.
-
-Evaluator responde:
-
-```text
-O agente respondeu bem?
-A resposta está fundamentada?
-A tool certa foi chamada?
-Houve regressão?
-```
-
-Certification responde:
-
-```text
-O agente está pronto para rodar?
-Endpoints funcionam?
-MCP funciona?
-Guardrails funcionam?
-Observabilidade funciona?
-```
-
-### 2. Arquitetura
-
-```mermaid
-flowchart LR
-    Runtime[Runtime] --> LF[Langfuse]
-    LF --> Eval[Offline Evaluator]
-    Dataset[Datasets] --> Eval
-    Eval --> Scores[Scores]
-    Eval --> Reports[Reports]
-    Cert[Certification Suite] --> Runtime
-    Cert --> Evidence[Evidences]
-```
-
-### 3. Métricas
-
-| Métrica | Descrição |
-| --- | --- |
-| quality | Clareza, completude e utilidade. |
-| groundedness | Aderência a evidências MCP/RAG. |
-| safety | Conformidade de segurança. |
-| resolution | Resolve a intenção. |
-| tool_correctness | Usa tools corretas. |
-| route_accuracy | Rota/intenção corretas. |
-| policy_compliance | Aderência à política de domínio. |
-
-
-### 4. Dataset
-
-```yaml
-dataset:
-  name: telecom_contas_regression
-  version: 1.0.0
-  items:
-    - id: billing-001
-      input: "Quero consultar minha fatura"
-      business_context:
-        customer_key: "11999999999"
-        contract_key: "3000131180"
-      expected:
-        route: billing_agent
-        tools:
-          - consultar_fatura
-        min_scores:
-          quality: 0.75
-          groundedness: 0.70
-```
-
-### 5. EvaluationRun
-
-```json
-{
-  "run_id": "eval-001",
-  "agent_id": "telecom_contas",
-  "source": "langfuse",
-  "period_start": "2026-06-18T00:00:00Z",
-  "period_end": "2026-06-19T00:00:00Z",
-  "status": "running"
-}
-```
-
-### 6. CLI
-
-```bash
-af-evaluator run   --agent-id telecom_contas   --dataset datasets/telecom_contas.yaml
-```
-
-### 7. Certification
-
-Valida:
-
-- health;
-- GatewayRequest;
-- routing;
-- identity;
-- MCP;
-- RAG;
-- guardrails;
-- judges;
-- memory;
-- checkpoint;
-- Langfuse;
-- OTEL.
-
-### 8. Evidências
-
-- JSON;
-- HTML;
-- TXT.GZ legado;
-- scores Langfuse;
-- logs;
-- traces;
-- screenshots quando aplicável.
-
-### 9. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Dataset só com casos felizes | Baixa cobertura. | Incluir negativos e bordas. |
-| Evaluator sem baseline | Sem comparação. | Registrar baseline. |
-| Certification sem MCP real/mock | Integração não validada. | Criar tool test. |
-| Judge sem threshold | Sem critério objetivo. | Definir threshold. |
-
-
-### 10. Critérios de aceite
-
-- [ ] Dataset versionado.
-- [ ] Evaluator executado.
-- [ ] Scores persistidos.
-- [ ] Certification executada.
-- [ ] Relatórios gerados.
-- [ ] Thresholds definidos.
-- [ ] Casos negativos incluídos.
-- [ ] Scores publicados quando aplicável.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/07_rag_business_context_and_grounding.md b/docs/developer/en/07_rag_business_context_and_grounding.md
index 7bfbdd5..cccffaf 100644
--- a/docs/developer/en/07_rag_business_context_and_grounding.md
+++ b/docs/developer/en/07_rag_business_context_and_grounding.md
@@ -1,73 +1,41 @@
-
-### RAG, BusinessContext and Grounding
+### RAG, BusinessContext, and Grounding
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **RAG, providers, BusinessContext, retrieved context and grounding**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **RAG, providers, BusinessContext, retrieved context, and grounding**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Rag, providers, businesscontext, retrieved context and grounding.
+RAG, providers, BusinessContext, retrieved context, and grounding.
 
 ### Consolidated technical content
 
-### RAG, Enterprise Providers, BusinessContext and Grounding
+### RAG, Enterprise Providers, BusinessContext, and Grounding
 
-This guide covers configurable retrieval and its relationship with tools, memory and agent context.
+Guide for integrating retrieved knowledge, selecting between RAG providers, configuring KBDB, using samples, MCP sufficiency, and using BusinessContext as a data contract.
 
-### Provider selection
+### How to use this document
 
-RAG is provider-based. The standard implementation and the enterprise KBDB implementation are selected through configuration rather than through domain branches in the agent code. Provider-specific connection/index settings remain environment/configuration concerns.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### Runtime role
+### Standard RAG Provider versus KBDB Enterprise
 
-Retrieved knowledge is injected into the execution context so the agent can ground informational responses. RAG does not replace transactional tool execution and it is not the same as long-term memory. Use RAG for external/reference knowledge, MCP for live business operations/data and LTM for durable user/customer facts.
+> Content consolidated from `docs/RAG_PROVIDER_KBDB.md`.
 
-### KBDB Enterprise
+The framework now supports two retrieval backends through the same `RagService` contract, without changing agents or `_retrieve_rag_context()`.
 
-The KBDB provider is an alternative backend with its own configuration while preserving the framework-facing retrieval contract. Agent code should not need to know which provider is active.
-
-### BusinessContext
-
-BusinessContext v2 carries generic business identifiers resolved from domain aliases. RAG filters, tool calls and telemetry can consume these canonical keys without introducing `msisdn`, invoice/order naming or other domain fields into shared modules.
-
-### MCP sufficiency and grounding
-
-When a tool result already contains sufficient authoritative data for the requested answer, the runtime can avoid unnecessary retrieval/composition work according to the configured response path. Conversely, a RAG answer must not claim a transactional action occurred merely because documentation describes how the action works.
-
-### Sample validation
-
-The project contains sample PDFs/policies for billing, orders, products, support and business-context/RAG flow. Use them to validate ingestion/embedding/retrieval and ask targeted questions whose expected answer is present in one document.
-
-### Source material consolidated
-
-- `docs/RAG_PROVIDER_KBDB.md`
-- `docs/README_rag_samples.md`
-- `Documentacao/README_TEMPLATE_BUSINESS_CONTEXT_V2.md`
-- operational RAG/cache notes in `Documentacao/README_FIRST_MAX_OPERATIONAL_FIXES.md`
-
-### Detailed normative and implementation reference
-
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### RAG provider implementation notes
-
-> Consolidated from `docs/RAG_PROVIDER_KBDB.md`.
-
-O framework passa a suportar dois backends de retrieval pelo mesmo contrato `RagService`, sem alterar os agentes nem `_retrieve_rag_context()`.
-
-### Seleção
+### Selection
 
 ```env
 RAG_PROVIDER=standard  # default: comportamento anterior
@@ -75,23 +43,23 @@ RAG_PROVIDER=standard  # default: comportamento anterior
 RAG_PROVIDER=kbdb      # KBDB enterprise
 ```
 
-A seleção é exclusiva por processo. Os dois RAGs não executam juntos e não compartilham vector store, graph store ou ingestão.
+Selection is exclusive per process. The two RAG implementations do not run together and do not share vector store, graph store, or ingestion.
 
 ### `standard`
 
-Mantém integralmente o RAG já existente no `agent_framework_oci`: `VECTOR_STORE_PROVIDER`, `GRAPH_STORE_PROVIDER`, embedding, query rewrite, compression, retrieval guardrails e geração continuam válidos.
+Fully preserves the existing RAG in `agent_framework_oci`: `VECTOR_STORE_PROVIDER`, `GRAPH_STORE_PROVIDER`, embedding, query rewrite, compression, retrieval guardrails, and generation remain valid.
 
 ### `kbdb`
 
-O framework integra somente a porta estável de serving do projeto KBDB:
+The framework integrates only the stable serving port of the KBDB project:
 
 `PKG_KB_SERVING.SEARCH_KNOWLEDGE_BASE`
 
-O pipeline enterprise continua externo ao runtime do agente e preserva sua própria arquitetura RAW → SILVER → GOLD, HVI/hybrid search, property graph, publicação, lifecycle, auditoria e observabilidade.
+The enterprise pipeline remains external to the agent runtime and preserves its own RAW → SILVER → GOLD architecture, HVI/hybrid search, property graph, publishing, lifecycle, audit, and observability.
 
-O envelope KBDB é adaptado para `RagResult`/`VectorDocument`; portanto os agentes existentes continuam chamando `_retrieve_rag_context()` e os retrieval guardrails do framework continuam depois do retrieval.
+The KBDB envelope is adapted to `RagResult`/`VectorDocument`; therefore existing agents continue calling `_retrieve_rag_context()` and the framework's retrieval guardrails continue after retrieval.
 
-### Configuração
+### Configuration
 
 ```env
 RAG_PROVIDER=kbdb
@@ -111,23 +79,23 @@ KBDB_METADATA_JSON=
 KBDB_MIN_SCORE=
 ```
 
-Quando `RAG_PROVIDER=kbdb`, `KBDB_DB_USER`, `KBDB_DB_PASSWORD` e `KBDB_DB_DSN` são obrigatórios. O KBDB usa conexão isolada porque pode residir em outro Autonomous. `KBDB_DB_DSN` segue a mesma semântica de `ADB_DSN`: use o alias TNS existente no `tnsnames.ora` da wallet indicada por `KBDB_DB_WALLET_LOCATION`, e não uma URL `tcps://...`.
+When `RAG_PROVIDER=kbdb`, `KBDB_DB_USER`, `KBDB_DB_PASSWORD`, and `KBDB_DB_DSN` are required. KBDB uses an isolated connection because it may reside in another Autonomous database. `KBDB_DB_DSN` follows the same semantics as `ADB_DSN`: use the existing TNS alias in the `tnsnames.ora` from the wallet indicated by `KBDB_DB_WALLET_LOCATION`, not a `tcps://...` URL.
 
-### Isolamento e compatibilidade
+### Isolation and compatibility
 
-- `RAG_PROVIDER=standard` não importa nem conecta ao KBDB.
-- `RAG_PROVIDER=kbdb` não instancia vector/graph stores do RAG padrão.
-- Ingestão por `RagService.add_documents()` não é permitida no modo KBDB: deve passar pelo pipeline/publicação KBDB.
-- Query rewrite e context compression continuam opcionais e são aplicados pela camada comum do framework.
-- `AgentRuntimeMixin._retrieve_rag_context()` e os agentes permanecem inalterados.
-- Falhas do KBDB seguem a semântica existente do framework: retrieval é evidência auxiliar e a exceção é convertida em metadata técnica sem derrubar a jornada.
+- `RAG_PROVIDER=standard` does not import or connect to KBDB.
+- `RAG_PROVIDER=kbdb` does not instantiate the standard RAG vector/graph stores.
+- Ingestion through `RagService.add_documents()` is not allowed in KBDB mode: it must go through the KBDB pipeline/publishing process.
+- Query rewrite and context compression remain optional and are applied by the framework's common layer.
+- `AgentRuntimeMixin._retrieve_rag_context()` and agents remain unchanged.
+- KBDB failures follow the framework's existing semantics: retrieval is auxiliary evidence and the exception is converted into technical metadata without breaking the user journey.
 
 
-### Resposta direta de tool e RAG
+### Direct tool response and RAG
 
-O framework não considera mais que um resultado MCP estruturado é, por si só, uma resposta suficiente ao usuário.
+The framework no longer considers a structured MCP result, by itself, to be a sufficient user response.
 
-Uma política `response.renderer` define somente **como** apresentar o resultado. Ela não encerra o fluxo antes de RAG/LLM. Para uma tool deliberadamente produzir uma resposta final direta, a aplicação deve declarar explicitamente:
+A `response.renderer` policy defines only **how** to present the result. It does not terminate the flow before RAG/LLM. For a tool to deliberately produce a direct final response, the application must explicitly declare:
 
 ```yaml
 response:
@@ -136,31 +104,23 @@ response:
   direct: true
 ```
 
-Sem `direct: true`, o resultado da tool permanece como evidência MCP e o fluxo segue para `_retrieve_rag_context()` e composição LLM. Isso permite, por exemplo, que uma consulta operacional de plano seja combinada com conhecimento documental do KBDB quando a pergunta pedir regras, políticas ou explicações.
+Without `direct: true`, the tool result remains MCP evidence and the flow continues to `_retrieve_rag_context()` and LLM composition. This allows, for example, an operational plan query to be combined with KBDB documentary knowledge when the question asks for rules, policies, or explanations.
 
-O core do framework não possui fallback por nome de tool (`consultar_plano`, `consultar_pedido`, etc.). Regras de apresentação pertencem à aplicação/domínio.
+The framework core has no fallback by tool name (`consultar_plano`, `consultar_pedido`, etc.). Presentation rules belong to the application/domain.
 
 
-### Suficiência MCP e grounding
+### MCP sufficiency and grounding
 
-Um resultado MCP bem-sucedido **não** faz o framework pular RAG automaticamente.
-O domínio só pode declarar suficiência documental explicitamente no payload com
-`rag_sufficient=true` ou `knowledge_sufficient=true`. Essa decisão é genérica e
-não depende do nome da tool nem de palavras-chave de telecom/retail.
+A successful MCP result **does not** make the framework skip RAG automatically.  
+The domain may declare documentary sufficiency only explicitly in the payload with `rag_sufficient=true` or `knowledge_sufficient=true`. This decision is generic and does not depend on the tool name or telecom/retail keywords.
 
-No provider `kbdb`, `KBDB_GROUNDED_ONLY=true` é o padrão. Quando a busca KBDB
-retorna vazia, bloqueada ou com erro, a composição LLM pode usar fatos comprovados
-por MCP/business context, mas não pode completar a parte documental com conhecimento
-paramétrico do modelo. Deve informar que não há evidência suficiente na base.
+For the `kbdb` provider, `KBDB_GROUNDED_ONLY=true` is the default. When KBDB search returns empty, blocked, or error, LLM composition may use facts proven by MCP/business context, but it must not fill the documentary portion using parametric model knowledge. It must state that there is insufficient evidence in the knowledge base.
 
-Eventos do ProductAgent registram `IC.PRODUCT_RAG_CONTEXT_EVALUATED` em toda
-tentativa/decisão e `IC.PRODUCT_RAG_CONTEXT_RETRIEVED` somente quando há contexto
-recuperado. Os metadados incluem `provider`, `status`, `document_count`, `reason`,
-`error`, `query`, `namespace` e `latency_ms`.
+ProductAgent events record `IC.PRODUCT_RAG_CONTEXT_EVALUATED` for every attempt/decision and `IC.PRODUCT_RAG_CONTEXT_RETRIEVED` only when context was retrieved. Metadata includes `provider`, `status`, `document_count`, `reason`, `error`, `query`, `namespace`, and `latency_ms`.
 
-### RAG sample validation guide
+### RAG samples and tests
 
-> Consolidated from `docs/README_rag_samples.md`.
+> Content consolidated from `docs/README_rag_samples.md`.
 
 These PDF files are synthetic, searchable sample documents created to validate the RAG embedding and retrieval flow of `agent_template_backend`.
 
@@ -216,588 +176,212 @@ OCI_EMBEDDING_MODEL=cohere.embed-multilingual-v3.0
 - What is the target response for a critical support ticket?
 - How does BusinessContext map customer_key to MCP tool parameters?
 
-### Runtime integration constraints
+### BusinessContext v2
 
-> Consolidated from `specs/SPEC-002-Agent-Runtime.md`.
+> Content consolidated from `Documentacao/README_TEMPLATE_BUSINESS_CONTEXT_V2.md`.
 
-### Escopo
+This package updates `agent_template_backend` and `agent_frontend` to reflect the new framework, where keys coming from the channel/front end are resolved once into canonical keys and propagated through the layers to the MCP Server.
 
-O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
+### Implemented flow
 
-### Componentes
+1. The front end sends `tenant_id`, `agent_id`, `session_id`, and `business_context`.
+2. The backend normalizes the message through `ChannelGateway`, preserving the full payload in `context`.
+3. The backend uses `IdentityResolver` with `config/identity.yaml` to generate `BusinessContext`:
+   - `customer_key`
+   - `contract_key`
+   - `interaction_key`
+   - `account_key`
+   - `resource_key`
+   - `session_key`
+4. The workflow receives `context.business_context`.
+5. Example agents no longer build specific arguments such as `msisdn`, `invoice_id`, or `order_id` directly.
+6. `MCPToolRouter` uses `config/mcp_parameter_mapping.yaml` to convert canonical keys into the actual parameters of each MCP tool.
 
-| Componente | Responsabilidade |
-|---|---|
-| Workflow Builder | Compila o grafo LangGraph. |
-| State Manager | Mantém o estado de execução. |
-| Session Manager | Resolve sessão e conversation_key. |
-| Memory Manager | Carrega e persiste histórico. |
-| Checkpoint Manager | Persiste estado LangGraph. |
-| Input Guardrail Node | Executa guardrails de entrada. |
-| Router Node | Decide rota/intent. |
-| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
-| Agent Node | Executa agente de domínio. |
-| MCP Client/Router | Executa tools por contrato. |
-| RAG Service | Recupera contexto documental. |
-| Output Supervisor | Revisa resposta antes de saída. |
-| Output Guardrail Node | Executa guardrails de saída. |
-| Judge Node | Avalia resposta. |
-| Persistence Node | Persiste mensagens, memória e checkpoint. |
+### Main files adjusted
 
-### State Model
+- `agent_template_backend/app/main.py`
+  - loads `IdentityResolver`;
+  - resolves `BusinessContext` per message;
+  - persists keys in session/memory/metadata/SSE;
+  - adds `/debug/identity`.
 
-```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    context: dict
-    business_context: dict
-    tool_arguments: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    rag_metadata: dict
-    guardrails: list[dict]
-    judges: list[dict]
-    metadata: dict
-    errors: list[dict]
+- `agent_template_backend/app/agents/runtime.py`
+  - adds centralized `_collect_mcp_context()`;
+  - forwards `business_context` and `original_context` to the MCP Router.
+
+- `agent_template_backend/app/agents/*_agent.py`
+  - agents now use `_collect_mcp_context()` instead of building specific arguments.
+
+- `agent_template_backend/config/identity.yaml`
+  - defines how channel/front-end fields feed canonical keys.
+
+- `agent_template_backend/config/mcp_parameter_mapping.yaml`
+  - defines how canonical keys become real parameters per MCP tool.
+
+- `agent_frontend/index.html` and `agent_frontend/app.js`
+  - add `tenant`, `agent`, and canonical-key fields;
+  - send `business_context` in the payload;
+  - retain domain aliases for compatibility (`msisdn`, `invoice_id`, `order_id`, etc.).
+
+### Quick test
+
+Start backend, frontend, and MCP servers. Then test:
+
+```bash
+curl -s http://localhost:8000/health | jq
+
+curl -s -X POST http://localhost:8000/debug/identity \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel":"web",
+    "tenant_id":"default",
+    "agent_id":"telecom_contas",
+    "payload":{
+      "message":"Minha fatura veio alta",
+      "session_id":"teste-001",
+      "msisdn":"11999999999",
+      "invoice_id":"3000131180",
+      "ura_call_id":"URA-123",
+      "business_context":{
+        "customer_key":"11999999999",
+        "contract_key":"3000131180",
+        "interaction_key":"URA-123",
+        "session_key":"teste-001"
+      }
+    }
+  }' | jq
+
+curl -s -X POST http://localhost:8000/debug/mcp/call/consultar_fatura \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "business_context": {
+      "customer_key":"11999999999",
+      "contract_key":"3000131180",
+      "interaction_key":"URA-123",
+      "session_key":"teste-001"
+    }
+  }' | jq
 ```
 
-### Workflow
+In the backend log, look for `mcp.tool.mapped`. It should indicate the mapped keys and `has_msisdn=true`, `has_invoice_id=true` for the telecom domain.
 
-```mermaid
-flowchart TD
-    A[start] --> B[input_guardrails]
-    B --> C[routing_decision]
-    C --> D[agent_execution]
-    D --> E[output_supervisor]
-    E --> F[output_guardrails]
-    F --> G[judge]
-    G --> H[persist]
-    H --> I[end]
-    C --> J[handoff]
-    J --> C
-```
+### Operational RAG and cache integration
 
-### Nós
+> Content consolidated from `Documentacao/README_FIRST_MAX_OPERATIONAL_FIXES.md`.
 
-| Nó | Entrada | Saída |
-|---|---|---|
-| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
-| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
-| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
-| `output_supervisor` | `response_text` | `response_text` revisado |
-| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
-| `judge` | `response_text`, evidências | `judges` |
-| `persist` | `state` completo | checkpoint, memória, mensagens |
+This version fixes the gaps identified in the comparison against FIRST.
 
-### Router
+### Applied fixes
 
-```yaml
-routing:
-  mode: router
-  fallback_agent: billing_agent
-  enable_llm_router: false
-  intents:
-    billing_invoice_explanation:
-      route: billing_agent
-      keywords:
-        - fatura
-        - cobrança
-        - boleto
-      mcp_tools:
-        - consultar_fatura
-        - consultar_pagamentos
-```
+### 1. Operational LangGraph checkpoint
 
-### Supervisor
-
-```yaml
-supervisor:
-  enabled: true
-  profile: supervisor
-  max_turns: 5
-  handoff_enabled: true
-  fallback_route: support_agent
-```
-
-### Memory
-
-| Provider | Uso |
-|---|---|
-| `memory` | Execução local e testes. |
-| `sqlite` | Desenvolvimento local persistente. |
-| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
-| `autonomous` | Produção com Oracle Autonomous Database. |
-
-### Checkpoints
-
-Checkpoint contém:
-
-```json
-{
-  "conversation_key": "default:telecom_contas:session-001",
-  "checkpoint_id": "ckpt-001",
-  "state": {},
-  "pending_writes": [],
-  "created_at": "2026-06-19T12:00:00Z"
-}
-```
-
-Formato entregue ao LangGraph:
-
-```python
-pending_writes: list[tuple[str, str, object]]
-```
-
-### Business Context
-
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
-
-### Ordem de Prioridade dos Dados
-
-1. `tool_arguments`
-2. `business_context`
-3. `context`
-4. `session.metadata`
-5. `state`
-6. extração complementar do texto
-
-### MCP Integration
-
-```mermaid
-flowchart LR
-    AgentNode --> ToolList[mcp_tools]
-    ToolList --> Mapping[mcp_parameter_mapping.yaml]
-    Mapping --> MCP[MCP Gateway/Router]
-    MCP --> Result[mcp_results]
-```
-
-### RAG Integration
-
-```yaml
-rag:
-  enabled: true
-  namespace_strategy: agent_id
-  top_k: 5
-  profile_generation: rag_generation
-```
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `runtime.started` | Execução iniciada. |
-| `runtime.session.loaded` | Sessão carregada. |
-| `runtime.memory.loaded` | Memória carregada. |
-| `runtime.checkpoint.loaded` | Checkpoint carregado. |
-| `runtime.route.selected` | Rota selecionada. |
-| `runtime.agent.started` | Agente iniciado. |
-| `runtime.agent.completed` | Agente concluído. |
-| `runtime.persist.completed` | Persistência concluída. |
-| `runtime.failed` | Falha controlada. |
-
-### Erros
-
-| Código | Condição | Tratamento |
-|---|---|---|
-| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
-| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
-| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
-| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
-| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
-| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
-
-
-
-### Contrato Durável de Estado Transacional
-
-Hosts que utilizam `AgentRuntime` com transações multi-turno DEVEM declarar no `AgentState` os campos `active_transaction` e `last_transaction`. O primeiro é a fonte canônica da transação em andamento e deve sobreviver a checkpoint/resume; o segundo mantém o snapshot da última transação terminal.
-
-```python
-active_transaction: dict[str, Any]
-last_transaction: dict[str, Any]
-```
-
-`selected_tool_call` e `pending_tool_call` são campos auxiliares/compatibilidade e não substituem o latch canônico. Durante `COLLECTING_PARAMETERS`, a retomada da transação e o consumo de parâmetros pendentes têm precedência sobre keyword routing genérico. Uma mudança de intenção só deve interromper a transação quando for inequívoca ou explicitamente solicitada pelo usuário.
-
-O contrato completo, ciclo de vida, precedência de roteamento, checklist e testes regressivos estão em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Runtime recebe GatewayRequest validado.
-- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
-- [ ] Input guardrails executam antes do roteamento.
-- [ ] Router ou Supervisor seleciona rota.
-- [ ] Agent Node executa sem acessar payload bruto de canal.
-- [ ] MCP é acessado por contrato.
-- [ ] RAG é acessado por serviço reutilizável.
-- [ ] Output guardrails executam antes da resposta final.
-- [ ] Judges geram JudgeResult.
-- [ ] Memória e checkpoint são persistidos conforme provider.
-- [ ] Hosts transacionais declaram `active_transaction` e `last_transaction` no `AgentState`.
-- [ ] Durante `COLLECTING_PARAMETERS`, respostas a parâmetros pendentes têm precedência sobre keyword routing genérico.
-- [ ] Erros geram NOC e resposta controlada.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Business context contracts
-
-> Consolidated from `specs/SPEC-012-Canonical-Contracts.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Contratos canônicos são estruturas padronizadas usadas para desacoplar canais, gateways, runtime, agentes, tools, LLMs, evaluator e observabilidade.
-
-A plataforma usa contratos para garantir que componentes independentes possam evoluir sem quebrar uns aos outros.
-
-### 2. Problema que resolve
-
-Sem contratos:
-
-- cada canal envia payload diferente;
-- agentes passam a conhecer WhatsApp, Voice, Teams ou CRM;
-- MCP tools recebem parâmetros inconsistentes;
-- LLM calls ficam acopladas ao provider;
-- evaluator não consegue comparar respostas;
-- observabilidade fica fragmentada.
-
-Com contratos:
+The workflow no longer compiles directly with `MemorySaver()`. The following adapter was created:
 
 ```text
-Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
+agent_framework/checkpoints/langgraph_saver.py
 ```
 
-### 3. Catálogo de contratos
+It connects LangGraph to the framework's configured repository:
 
-| Contrato | Uso |
-| --- | --- |
-| GatewayRequest | Entrada canônica da plataforma. |
-| ChannelResponse | Resposta canônica ao canal. |
-| BusinessContext | Identidade canônica de negócio. |
-| AgentState | Estado interno do runtime. |
-| Session | Sessão técnica/conversacional. |
-| Checkpoint | Persistência de estado LangGraph. |
-| ToolInvocation | Chamada canônica de tool MCP. |
-| ToolResult | Resposta canônica de tool MCP. |
-| LLMRequest | Chamada canônica ao AI Gateway. |
-| LLMResponse | Resposta canônica do AI Gateway. |
-| EvaluationRun | Execução do evaluator. |
-| EvaluationResult | Resultado de avaliação. |
-| CertificationResult | Resultado de certificação. |
-| EventEnvelope | Envelope de eventos IC/NOC/GRL. |
+- `memory`
+- `sqlite`
+- `oracle` / `autonomous`
 
-
-### 4. GatewayRequest
-
-### 4.1. Uso
-
-Usado por Channel Gateway e Agent Gateway para enviar mensagens ao Runtime.
-
-```json
-{
-  "channel": "web",
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "payload": {
-    "message": "Quero consultar minha fatura",
-    "session_id": "session-001",
-    "user_id": "user-001",
-    "message_id": "msg-001",
-    "business_context": {
-      "customer_key": "11999999999",
-      "contract_key": "3000131180",
-      "interaction_key": "301953872",
-      "session_key": "session-001"
-    },
-    "metadata": {
-      "request_id": "req-001",
-      "contract_version": "gateway-request-v1"
-    }
-  }
-}
-```
-
-### 4.2. Campos obrigatórios
-
-- `channel`;
-- `payload.message`;
-- `payload.session_id`;
-- `payload.message_id`;
-- `tenant_id` quando multi-tenant;
-- `agent_id` quando não houver roteamento global.
-
-### 5. ChannelResponse
-
-```json
-{
-  "channel": "web",
-  "session_id": "default:telecom_contas:session-001",
-  "text": "Resposta final do agente.",
-  "metadata": {
-    "tenant_id": "default",
-    "agent_id": "telecom_contas",
-    "route": "billing_agent",
-    "intent": "billing_invoice_explanation",
-    "guardrails": [],
-    "judges": []
-  }
-}
-```
-
-### 6. BusinessContext
-
-### 6.1. Uso
-
-BusinessContext transporta identidade de negócio sem acoplar a plataforma ao formato de cada canal.
-
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
-
-### 6.2. Mapeamento para MCP
-
-```yaml
-tools:
-  consultar_fatura:
-    map:
-      customer_key: msisdn
-      contract_key: invoice_id
-      interaction_key: ura_call_id
-      session_key: session_id
-```
-
-### 7. AgentState
+In the workflow:
 
 ```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    business_context: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    guardrails: list[dict]
-    judges: list[dict]
+builder.compile(checkpointer=create_langgraph_checkpointer(self.settings))
 ```
 
-### 8. ToolInvocation
+### 2. LangGraph telemetry wrapping actual execution
 
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "tool_name": "consultar_fatura",
-  "arguments": {
-    "msisdn": "11999999999",
-    "invoice_id": "3000131180"
-  },
-  "business_context": {
-    "customer_key": "11999999999",
-    "contract_key": "3000131180"
-  },
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
+A node wrapper was added to the workflow:
+
+```python
+self._node("billing_agent", self.billing_agent)
 ```
 
-### 9. ToolResult
+This way the `langgraph.node.*` span/event wraps actual node execution, not just an empty block.
 
-```json
-{
-  "tool_name": "consultar_fatura",
-  "ok": true,
-  "data": {
-    "invoice_id": "3000131180",
-    "valor_total": 249.90,
-    "status": "ABERTA"
-  },
-  "cache": {
-    "hit": false,
-    "ttl_seconds": 300
-  },
-  "latency_ms": 140
-}
+Events emitted:
+
+- `langgraph.node.started`
+- `langgraph.node.completed`
+- `langgraph.node.failed`
+- `langgraph.edge.selected`
+
+### 3. RAG integrated into agents
+
+Agents now receive `RagService` and use retrieved context in the prompt:
+
+- BillingAgent
+- ProductAgent
+- OrdersAgent
+- SupportAgent
+
+RAG uses:
+
+- `VECTOR_STORE_PROVIDER=memory|sqlite|oracle|autonomous`
+- `GRAPH_STORE_PROVIDER=memory|oracle|autonomous`
+- `RAG_TOP_K`
+
+### 4. Cache integrated into agent runtime
+
+The following mixin was created:
+
+```text
+agent_template_backend/app/agents/runtime.py
 ```
 
-### 10. LLMRequest
+It adds:
 
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "profile": "judge",
-  "operation": "judge.response_quality",
-  "messages": [
-    {"role": "system", "content": "Você é um avaliador."},
-    {"role": "user", "content": "Avalie a resposta."}
-  ],
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
+- standardized RAG retrieval;
+- cache key for LLM calls;
+- hit/miss with telemetry;
+- distributed cache through `create_cache(settings)`.
+
+### 5. Unit tests
+
+The following directory was created:
+
+```text
+tests/unit
 ```
 
-### 11. LLMResponse
+Initial coverage:
 
-```json
-{
-  "provider": "oci_openai",
-  "model": "openai.gpt-4.1",
-  "profile": "judge",
-  "content": "Resultado",
-  "usage": {
-    "input_tokens": 1200,
-    "output_tokens": 300,
-    "total_tokens": 1500
-  },
-  "latency_ms": 820
-}
+- cache;
+- SSE;
+- RAG;
+- checkpoint saver;
+- LangGraph telemetry;
+- agent runtime;
+- static workflow verification;
+- main imports.
+
+Local validation performed:
+
+```text
+12 passed
 ```
 
-### 12. EvaluationRun
+### How to test
 
-```json
-{
-  "run_id": "eval-001",
-  "agent_id": "telecom_contas",
-  "source": "langfuse",
-  "period_start": "2026-06-18T00:00:00Z",
-  "period_end": "2026-06-19T00:00:00Z",
-  "status": "running"
-}
+```bash
+cd projeto_agent_framework_first_ready
+pip install -r agent_template_backend/requirements.txt
+pytest -q tests/unit
 ```
 
-### 13. EventEnvelope
+### Source files
 
-```json
-{
-  "event_type": "IC.AGENT_COMPLETED",
-  "timestamp": "2026-06-19T12:00:00Z",
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "session_id": "session-001",
-  "trace_id": "trace-001",
-  "payload": {}
-}
-```
+The files below were consolidated into this manual:
 
-### 14. Regras de evolução
+- `docs/RAG_PROVIDER_KBDB.md`
+- `docs/README_rag_samples.md`
+- `Documentacao/README_TEMPLATE_BUSINESS_CONTEXT_V2.md`
+- `Documentacao/README_FIRST_MAX_OPERATIONAL_FIXES.md`
 
-- campos novos devem ser opcionais;
-- campos obrigatórios não podem ser removidos dentro da mesma major;
-- mudança semântica exige nova versão;
-- contratos são versionados independentemente.
+### Maintenance rule
 
-### 15. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Payload bruto no Runtime | Acopla canais ao core. | Usar GatewayRequest. |
-| Tool recebendo BusinessContext bruto sem mapping | Quebra contrato da tool. | Usar mcp_parameter_mapping.yaml. |
-| LLM direto no agente | Quebra AI Gateway. | Usar LLMRequest/profile. |
-| Campos sem versão | Dificulta migração. | Declarar contract_version. |
-
-
-### 16. Critérios de aceite
-
-- [ ] GatewayRequest documentado e versionado.
-- [ ] ChannelResponse documentado e versionado.
-- [ ] BusinessContext usado por canais e MCP.
-- [ ] ToolInvocation e ToolResult padronizados.
-- [ ] LLMRequest e LLMResponse padronizados.
-- [ ] EvaluationRun e EvaluationResult padronizados.
-- [ ] EventEnvelope usado para IC/NOC/GRL.
-- [ ] Contratos possuem regras de evolução.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/08_long_term_memory_and_checkpoint.md b/docs/developer/en/08_long_term_memory_and_checkpoint.md
index 85c90de..8345453 100644
--- a/docs/developer/en/08_long_term_memory_and_checkpoint.md
+++ b/docs/developer/en/08_long_term_memory_and_checkpoint.md
@@ -1,80 +1,43 @@
-
 ### Long-Term Memory and Checkpoint
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **LTM, conversation memory, identity isolation and state persistence**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **LTM, conversation memory, identity-based isolation, and state persistence**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Ltm, conversation memory, identity isolation and state persistence.
+LTM, conversation memory, identity-based isolation, and state persistence.
 
 ### Consolidated technical content
 
 ### Long-Term Memory and Enterprise Checkpointing
 
-This is the developer implementation guide for durable memory and graph-state persistence.
+Implementation manual for durable memory, identity isolation, stores, extraction, LangGraph integration, persistence testing, and the differences among LTM, history, summary, and checkpoint.
 
-### Memory types
+### How to use this document
 
-Conversation memory is short-lived turn history used for current conversational continuity. Summary memory compresses conversation history. Long-Term Memory stores durable facts that should survive session changes. These mechanisms solve different problems and must not be treated as interchangeable.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### LTM components
+### Complete Long-Term Memory implementation
 
-The reference implementation uses `LongTermMemoryManager`, an abstract `LongTermMemoryStore`, concrete SQLite/in-memory stores, a `LongTermMemoryExtractor`, `LongTermMemoryItem` records and runtime/workflow integration through a `persist_long_term_memory` node.
-
-### Identity and isolation
-
-LTM must be keyed by stable business identity such as tenant, agent and customer key rather than by ephemeral frontend session alone. Retrieval in a later session should return the same customer's durable facts while remaining isolated from other tenants/agents/customers.
-
-### Execution flow
-
-At runtime, relevant durable memories are loaded into the agent context before response composition. After the turn, the extractor decides which candidate facts are worth persisting. The store writes the accepted items. Resetting a frontend session should not erase durable memory unless an explicit deletion policy is invoked.
-
-### Checkpointing
-
-Enterprise checkpointing persists LangGraph execution state and enables controlled resume after another turn or process restart. It is technical workflow persistence, not durable user memory.
-
-A checkpoint must not become the source of truth for the active business transaction. Resume logic still uses canonical transaction state to determine whether there is an active paused workflow.
-
-### Testing
-
-Validate: persistence after a turn, retrieval from a different session for the same identity, isolation across identities, frontend reset, backend restart, direct SQLite/store verification and disabled-LTM behavior. For checkpointing, validate pause/resume plus completed/cancelled transaction non-resumption.
-
-### Reference implementation limitations
-
-The local SQLite/in-memory stores are reference implementations. Production deployments should select storage, retention, encryption and privacy policies appropriate to the environment. Extraction quality depends on the configured model/prompt and should be tested with domain-specific examples.
-
-### Source material consolidated
-
-- `Documentacao/Manual_Long_Term_Memory_PT.md`
-- `Documentacao/Long_Term_Memory_Implementation_Guide_EN.md`
-- `Documentacao/README_CHECKPOINT_ENTERPRISE.md`
-
-### Detailed normative and implementation reference
-
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### Full Long-Term Memory implementation guide
-
-> Consolidated from `Documentacao/Long_Term_Memory_Implementation_Guide_EN.md`.
+> Content consolidated from `Documentacao/Manual_Long_Term_Memory_PT.md`.
 
 ### Concept
 
-Long-Term Memory (LTM) is the `agent_framework` capability that stores and retrieves durable facts beyond the lifetime of a conversation session.
+Long-Term Memory (LTM) is the `agent_framework` capability to store and retrieve durable facts beyond the lifetime of a conversation session.
 
-Unlike message history, which is normally associated with a `session_id`, Long-Term Memory is associated with the business identity of the user or customer. In the current implementation, this identity consists of:
+Unlike message history, which is normally associated with a `session_id`, long-term memory is associated with the business identity of the user or customer. In the current implementation, this identity is composed of:
 
 ```text
 tenant_id
@@ -82,57 +45,57 @@ agent_id
 customer_key
 ```
 
-This allows an agent to retrieve preferences, identity information, projects and constraints even when a new session is created.
+This allows an agent to retrieve preferences, identity information, projects, and constraints even when a new session is created.
 
-### Purpose
+### What it is for
 
 Long-Term Memory is used to:
 
 - maintain continuity across sessions;
 - personalize responses;
-- prevent users from repeating previously supplied information;
-- reduce the need to send the full conversation history to the model;
-- store preferences, current projects, preferred names and constraints;
-- isolate memory across tenants, agents and customers.
+- avoid making the user repeat information already provided;
+- reduce the need to send the entire history to the model;
+- store preferences, current projects, preferred names, and constraints;
+- isolate memory across tenants, agents, and customers.
 
 Example:
 
 ```text
-Session A:
-"Call me Cris. My preferred language is Python."
+Sessão A:
+"Me chame de Cris. Minha linguagem preferida é Python."
 
-Session B, with another session_id and the same customer_key:
-"What do you remember about me?"
+Sessão B, com outro session_id e o mesmo customer_key:
+"O que você lembra sobre mim?"
 
-Expected response:
-"Your preferred name is Cris and your preferred language is Python."
+Resposta esperada:
+"Seu nome preferido é Cris e sua linguagem preferida é Python."
 ```
 
-### Memory type differences
+### Difference among memory types
 
 ### Conversation Memory
 
-Stores messages from the current conversation and is normally associated with the `session_id`.
+Maintains messages from the current conversation and is normally associated with `session_id`.
 
 ### Summary Memory
 
-Stores a summary of the conversation to reduce the context size sent to the model.
+Maintains a conversation summary to reduce the amount of context sent to the model.
 
 ### Long-Term Memory
 
-Stores durable facts across sessions and is associated with the business identity, primarily the `customer_key`.
+Maintains durable facts across sessions and is associated with business identity, especially `customer_key`.
 
-### Components
+### Feature components
 
 ### LongTermMemoryManager
 
-Coordinates:
+Responsible for coordinating:
 
 - memory loading;
-- identity-based retrieval;
+- retrieval by identity;
 - context rendering;
-- durable fact extraction;
-- fact persistence;
+- extraction of new facts;
+- persistence of facts;
 - deduplication and updates.
 
 ### LongTermMemoryStore
@@ -143,10 +106,10 @@ Persistence interface used by the manager.
 
 Reference implementation based on SQLite.
 
-It is suitable for:
+It is appropriate for:
 
 - local development;
-- testing;
+- tests;
 - demonstrations;
 - low-scale environments.
 
@@ -154,13 +117,13 @@ It is suitable for:
 
 In-memory implementation used for quick tests.
 
-Its content is lost when the backend process stops.
+Its content is lost when the backend process terminates.
 
 ### LongTermMemoryExtractor
 
-Identifies durable facts in messages.
+Responsible for identifying durable facts in messages.
 
-Examples:
+Examples of facts:
 
 ```text
 preferred_name = Cris
@@ -170,15 +133,15 @@ current_project = Atlas
 
 ### LongTermMemoryItem
 
-Data model representing a persisted item, including identity, key, value, category, confidence and metadata.
+Model representing a persisted item, including identity, key, value, category, confidence, and metadata.
 
 ### AgentRuntime
 
-Loads memory before agent execution and injects the rendered context into the prompt.
+Loads memory before agent execution and injects the context into the prompt.
 
-### persist_long_term_memory node
+### `persist_long_term_memory` node
 
-LangGraph node responsible for persisting facts after the final response has been generated and validated.
+LangGraph node responsible for persisting facts after final-response generation and validation.
 
 ### File structure
 
@@ -198,42 +161,42 @@ libs/
 ### Execution flow
 
 ```text
-User message
-     │
-     ▼
+Mensagem do usuário
+        │
+        ▼
 AgentRuntime.prepare_memory_context()
-     │
-     ├── Conversation Memory
-     ├── Summary Memory
-     └── Long-Term Memory
-                 │
-                 ▼
-       long_term_memory_context
-                 │
-                 ▼
-            Agent prompt
-                 │
-                 ▼
-               Agent
-                 │
-                 ▼
-    Guardrails / Judges / Supervisor
-                 │
-                 ▼
-      persist_long_term_memory
-                 │
-                 ▼
-       LongTermMemoryExtractor
-                 │
-                 ▼
-        LongTermMemoryStore
+        │
+        ├── Conversation Memory
+        ├── Summary Memory
+        └── Long-Term Memory
+                    │
+                    ▼
+          long_term_memory_context
+                    │
+                    ▼
+             Prompt do agente
+                    │
+                    ▼
+                 Agente
+                    │
+                    ▼
+       Guardrails / Judges / Supervisor
+                    │
+                    ▼
+       persist_long_term_memory
+                    │
+                    ▼
+          LongTermMemoryExtractor
+                    │
+                    ▼
+           LongTermMemoryStore
 ```
 
 ### Framework configuration
 
 ### New modules
 
-Copy:
+Copy the files:
 
 ```text
 libs/agent_framework/src/agent_framework/memory/long_term_extractor.py
@@ -242,7 +205,7 @@ libs/agent_framework/src/agent_framework/memory/long_term_models.py
 libs/agent_framework/src/agent_framework/memory/long_term_store.py
 ```
 
-### Update memory/__init__.py
+### Updating `memory/__init__.py`
 
 Export the Long-Term Memory components:
 
@@ -260,9 +223,9 @@ from agent_framework.memory.long_term_store import (
 )
 ```
 
-### Update settings.py
+### Updating `settings.py`
 
-Add:
+Add the configurations:
 
 ```python
 ENABLE_LONG_TERM_MEMORY: bool = False
@@ -275,17 +238,17 @@ LONG_TERM_MEMORY_AUTO_EXTRACT: bool = True
 LONG_TERM_MEMORY_INJECT_CONTEXT: bool = True
 ```
 
-### AgentRuntime integration
+### Integration with AgentRuntime
 
 The runtime must:
 
-1. verify that the feature is enabled;
-2. create the manager when needed;
-3. retrieve facts using the identity;
-4. populate the workflow state;
-5. inject the rendered context into the prompt.
+1. check whether the feature is enabled;
+2. create the manager when necessary;
+3. retrieve facts by identity;
+4. populate state;
+5. inject context into the prompt.
 
-State fields:
+Fields added to state:
 
 ```python
 long_term_memories: list[dict]
@@ -293,9 +256,9 @@ long_term_memory_context: str
 long_term_memory_write_result: dict
 ```
 
-### AgentWorkflow initialization
+### Initialization in AgentWorkflow
 
-Create the manager in `AgentWorkflow`:
+The manager must be created in `AgentWorkflow`:
 
 ```python
 self.long_term_memory_manager = create_long_term_memory_manager(
@@ -306,7 +269,7 @@ self.long_term_memory_manager = create_long_term_memory_manager(
 
 ### Correct agent initialization
 
-Do not pass `long_term_memory_manager` through `agent_kwargs` when the constructors of `BillingAgent`, `ProductAgent`, `OrdersAgent` and `SupportAgent` do not declare that parameter.
+`long_term_memory_manager` must not be passed through `agent_kwargs` if the constructors of `BillingAgent`, `ProductAgent`, `OrdersAgent`, and `SupportAgent` do not declare that parameter.
 
 This initialization causes an error:
 
@@ -329,7 +292,7 @@ TypeError: BillingAgent.__init__() got an unexpected keyword argument
 'long_term_memory_manager'
 ```
 
-The recommended approach is to create agents using their existing signatures and inject the manager as an attribute after initialization:
+The recommended form is to create agents using the existing signature and inject the manager as an attribute after initialization:
 
 ```python
 agent_kwargs = {
@@ -357,7 +320,7 @@ for agent in (
     agent.long_term_memory_manager = self.long_term_memory_manager
 ```
 
-This approach avoids changing every agent constructor and keeps the feature encapsulated in the framework.
+This approach avoids changing every agent constructor and keeps the capability encapsulated in the framework.
 
 ### LangGraph configuration
 
@@ -373,7 +336,7 @@ builder.add_node(
 )
 ```
 
-Update the edges:
+Change the flow:
 
 ```python
 builder.add_edge(
@@ -386,7 +349,7 @@ builder.add_edge(
 )
 ```
 
-Implement:
+Implement the method:
 
 ```python
 async def persist_long_term_memory(
@@ -429,9 +392,9 @@ LONG_TERM_MEMORY_INJECT_CONTEXT=true
 
 ### SQLite database path
 
-A relative path is resolved from the directory in which the backend is started.
+The relative path is resolved from the directory where the backend is started.
 
-To prevent different databases from being created accidentally, prefer an absolute path in development environments:
+To avoid accidentally creating different databases, prefer an absolute path in development environments:
 
 ```env
 LONG_TERM_MEMORY_SQLITE_PATH=/mnt/c/Asus_Projects/agent_platform_oci_long_term_memory/data/agent_framework.db
@@ -443,9 +406,9 @@ Create the directory before starting:
 mkdir -p data
 ```
 
-### Testing
+### How to test
 
-### Test 1 — Persistence
+### Test 1 — Write
 
 Send:
 
@@ -453,28 +416,28 @@ Send:
 {
   "session_id": "default:telecom_contas:memory-session-a",
   "customer_key": "11999999999",
-  "message": "Call me Cris. My preferred language is Python and my current project is Atlas."
+  "message": "Me chame de Cris. Minha linguagem preferida é Python e meu projeto atual se chama Atlas."
 }
 ```
 
 ### Test 2 — Retrieval in another session
 
-Use another `session_id` while keeping the same `customer_key`:
+Use another `session_id`, keeping the same `customer_key`:
 
 ```json
 {
   "session_id": "default:telecom_contas:memory-session-b",
   "customer_key": "11999999999",
-  "message": "What do you remember about me, my preferences and my project?"
+  "message": "O que você lembra sobre mim, minhas preferências e meu projeto?"
 }
 ```
 
 Expected result:
 
 ```text
-Your preferred name is Cris.
-Your preferred language is Python.
-Your current project is Atlas.
+Seu nome preferido é Cris.
+Sua linguagem preferida é Python.
+Seu projeto atual se chama Atlas.
 ```
 
 ### Test 3 — Isolation
@@ -484,18 +447,18 @@ Use another customer:
 ```json
 {
   "session_id": "default:telecom_contas:memory-session-c",
-  "customer_key": "another-customer",
-  "message": "What is my preferred name and current project?"
+  "customer_key": "outro-cliente",
+  "message": "Qual é meu nome preferido e qual é meu projeto atual?"
 }
 ```
 
-The data associated with `11999999999` must not be returned.
+The data for `11999999999` must not appear.
 
-### Test 4 — Frontend reset
+### Test 4 — Frontend restart
 
-Restart or reset the frontend and verify that it still sends the same `customer_key`.
+Restart or reset the frontend and confirm that it continues sending the same `customer_key`.
 
-Memory must survive a `session_id` change. Resetting the frontend does not delete the SQLite database.
+Memory must survive the `session_id` change. Resetting the frontend does not erase SQLite.
 
 ### Test 5 — Backend restart
 
@@ -515,11 +478,11 @@ With:
 LONG_TERM_MEMORY_PROVIDER=memory
 ```
 
-memory is lost when the process stops.
+memory will be lost when the process terminates.
 
-### Direct SQLite verification
+### Direct verification in SQLite
 
-Find the database:
+Locate the database:
 
 ```bash
 find . -name "agent_framework.db" -type f
@@ -531,7 +494,7 @@ Open it:
 sqlite3 ./data/agent_framework.db
 ```
 
-Query:
+Query it:
 
 ```sql
 SELECT
@@ -556,621 +519,117 @@ The implementation is working when:
 - the same `customer_key` retrieves previous facts;
 - another `customer_key` cannot access those facts;
 - restarting the frontend does not erase memory;
-- restarting the backend does not erase memory when using SQLite;
-- the `persist_long_term_memory` node runs;
+- restarting the backend does not erase memory when the provider is SQLite;
+- the `persist_long_term_memory` node executes;
 - the prompt receives `long_term_memory_context`.
 
 ### Best practices
 
 - Persist only durable facts.
-- Do not store the complete conversation as Long-Term Memory.
-- Isolate data by `tenant_id`, `agent_id` and `customer_key`.
-- Do not use `session_id` as the permanent user identity.
+- Do not store the full conversation as Long-Term Memory.
+- Isolate data by `tenant_id`, `agent_id`, and `customer_key`.
+- Do not use `session_id` as the user's permanent identity.
 - Persist only after final validations.
-- Avoid persisting temporary tool results.
-- Record telemetry for reads, writes, updates and failures.
+- Avoid storing temporary tool results.
+- Record read, write, update, and failure telemetry.
 - Define retention and deletion policies.
-- Use an absolute SQLite path in environments with multiple working directories.
-- Move to an enterprise database for production and high-availability environments.
+- Use an absolute SQLite path in environments with multiple execution directories.
+- Migrate to an enterprise database for production and high-availability environments.
 
-### Reference implementation limitations
+### Reference-implementation limitations
 
 The current implementation uses rule-based extraction and SQLite as the reference provider.
 
-Recommended future enhancements:
+Recommended evolutions:
 
-- LLM-based fact extraction;
-- vector-based semantic memory;
+- fact extraction with LLM;
+- semantic memory with vectors;
 - episodic memory;
 - expiration and versioning;
 - semantic deduplication;
-- consent policies;
-- query and deletion APIs;
+- consent policy;
+- query and deletion API;
 - Oracle Autonomous Database provider;
 - encryption and sensitive-data classification.
 
-### Runtime persistence responsibilities
+### Enterprise Checkpointing in LangGraph
 
-> Consolidated from `specs/SPEC-002-Agent-Runtime.md`.
+> Content consolidated from `Documentacao/README_CHECKPOINT_ENTERPRISE.md`.
 
-### Escopo
+This version adds four capabilities to the LangGraph checkpointer used by the framework:
 
-O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
+1. **Checkpoint Integrity**: each checkpoint is stored inside an envelope containing `schema_version`, `checkpoint_id`, SHA-256 `payload_hash`, and `created_at`. On read, the hash is recalculated. If the payload was truncated, changed, or corrupted, the checkpoint is ignored during recovery.
+2. **Checkpoint Compaction**: old checkpoints are automatically removed according to `CHECKPOINT_COMPACT_EVERY` and `CHECKPOINT_KEEP_LAST`. This prevents unbounded growth of the `workflow_checkpoints` table.
+3. **Resilient Checkpointer**: writes and reads use retry with backoff and jitter. The resilient layer works over memory, SQLite, and Oracle/Autonomous Database.
+4. **Checkpoint Recovery**: when restoring state, the framework scans recent checkpoints and returns the newest valid one, skipping corrupted checkpoints.
 
-### Componentes
+### Configuration
 
-| Componente | Responsabilidade |
-|---|---|
-| Workflow Builder | Compila o grafo LangGraph. |
-| State Manager | Mantém o estado de execução. |
-| Session Manager | Resolve sessão e conversation_key. |
-| Memory Manager | Carrega e persiste histórico. |
-| Checkpoint Manager | Persiste estado LangGraph. |
-| Input Guardrail Node | Executa guardrails de entrada. |
-| Router Node | Decide rota/intent. |
-| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
-| Agent Node | Executa agente de domínio. |
-| MCP Client/Router | Executa tools por contrato. |
-| RAG Service | Recupera contexto documental. |
-| Output Supervisor | Revisa resposta antes de saída. |
-| Output Guardrail Node | Executa guardrails de saída. |
-| Judge Node | Avalia resposta. |
-| Persistence Node | Persiste mensagens, memória e checkpoint. |
+In `.env`:
 
-### State Model
+```env
+CHECKPOINT_REPOSITORY_PROVIDER=sqlite
+ENABLE_RESILIENT_CHECKPOINTER=true
+ENABLE_CHECKPOINT_INTEGRITY=true
+ENABLE_CHECKPOINT_COMPACTION=true
+CHECKPOINT_COMPACT_EVERY=50
+CHECKPOINT_KEEP_LAST=20
+CHECKPOINT_RECOVERY_SCAN_LIMIT=25
+CHECKPOINT_RETRY_MAX_ATTEMPTS=3
+CHECKPOINT_RETRY_BASE_DELAY_SECONDS=0.05
+CHECKPOINT_RETRY_MAX_DELAY_SECONDS=1.0
+CHECKPOINT_RETRY_JITTER_SECONDS=0.05
+```
+
+For production with multiple pods, prefer:
+
+```env
+CHECKPOINT_REPOSITORY_PROVIDER=autonomous
+ADB_USER=...
+ADB_PASSWORD=...
+ADB_DSN=...
+ADB_WALLET_LOCATION=...
+ADB_TABLE_PREFIX=AGENTFW
+```
+
+### Use in LangGraph
 
 ```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    context: dict
-    business_context: dict
-    tool_arguments: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    rag_metadata: dict
-    guardrails: list[dict]
-    judges: list[dict]
-    metadata: dict
-    errors: list[dict]
+from agent_framework.checkpoints import create_langgraph_checkpointer
+
+checkpointer = create_langgraph_checkpointer(settings)
+graph = builder.compile(checkpointer=checkpointer)
+
+config = {"configurable": {"thread_id": session_id}}
+result = graph.invoke(input_state, config=config)
 ```
 
-### Workflow
+`thread_id` remains the conversation-recovery key. In an environment with a Load Balancer, any pod can resume execution if it uses the same persistent repository.
 
-```mermaid
-flowchart TD
-    A[start] --> B[input_guardrails]
-    B --> C[routing_decision]
-    C --> D[agent_execution]
-    D --> E[output_supervisor]
-    E --> F[output_guardrails]
-    F --> G[judge]
-    G --> H[persist]
-    H --> I[end]
-    C --> J[handoff]
-    J --> C
+### Files changed
+
+- `agent_framework/src/agent_framework/checkpoints/checkpoint_repository.py`
+- `agent_framework/src/agent_framework/checkpoints/langgraph_saver.py`
+- `agent_framework/src/agent_framework/checkpoints/__init__.py`
+- `agent_framework/src/agent_framework/config/settings.py`
+- `tests/unit/test_resilient_checkpointer.py`
+
+### Important note
+
+The `memory` provider now also uses `RepositoryCheckpointSaver` when `ENABLE_RESILIENT_CHECKPOINTER=true`. To return to LangGraph's pure `MemorySaver` for local tests, configure:
+
+```env
+ENABLE_RESILIENT_CHECKPOINTER=false
+CHECKPOINT_REPOSITORY_PROVIDER=memory
 ```
 
-### Nós
+### Source files
 
-| Nó | Entrada | Saída |
-|---|---|---|
-| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
-| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
-| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
-| `output_supervisor` | `response_text` | `response_text` revisado |
-| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
-| `judge` | `response_text`, evidências | `judges` |
-| `persist` | `state` completo | checkpoint, memória, mensagens |
+The files below were consolidated into this manual:
 
-### Router
+- `Documentacao/Manual_Long_Term_Memory_PT.md`
+- `Documentacao/README_CHECKPOINT_ENTERPRISE.md`
 
-```yaml
-routing:
-  mode: router
-  fallback_agent: billing_agent
-  enable_llm_router: false
-  intents:
-    billing_invoice_explanation:
-      route: billing_agent
-      keywords:
-        - fatura
-        - cobrança
-        - boleto
-      mcp_tools:
-        - consultar_fatura
-        - consultar_pagamentos
-```
+### Maintenance rule
 
-### Supervisor
-
-```yaml
-supervisor:
-  enabled: true
-  profile: supervisor
-  max_turns: 5
-  handoff_enabled: true
-  fallback_route: support_agent
-```
-
-### Memory
-
-| Provider | Uso |
-|---|---|
-| `memory` | Execução local e testes. |
-| `sqlite` | Desenvolvimento local persistente. |
-| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
-| `autonomous` | Produção com Oracle Autonomous Database. |
-
-### Checkpoints
-
-Checkpoint contém:
-
-```json
-{
-  "conversation_key": "default:telecom_contas:session-001",
-  "checkpoint_id": "ckpt-001",
-  "state": {},
-  "pending_writes": [],
-  "created_at": "2026-06-19T12:00:00Z"
-}
-```
-
-Formato entregue ao LangGraph:
-
-```python
-pending_writes: list[tuple[str, str, object]]
-```
-
-### Business Context
-
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
-
-### Ordem de Prioridade dos Dados
-
-1. `tool_arguments`
-2. `business_context`
-3. `context`
-4. `session.metadata`
-5. `state`
-6. extração complementar do texto
-
-### MCP Integration
-
-```mermaid
-flowchart LR
-    AgentNode --> ToolList[mcp_tools]
-    ToolList --> Mapping[mcp_parameter_mapping.yaml]
-    Mapping --> MCP[MCP Gateway/Router]
-    MCP --> Result[mcp_results]
-```
-
-### RAG Integration
-
-```yaml
-rag:
-  enabled: true
-  namespace_strategy: agent_id
-  top_k: 5
-  profile_generation: rag_generation
-```
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `runtime.started` | Execução iniciada. |
-| `runtime.session.loaded` | Sessão carregada. |
-| `runtime.memory.loaded` | Memória carregada. |
-| `runtime.checkpoint.loaded` | Checkpoint carregado. |
-| `runtime.route.selected` | Rota selecionada. |
-| `runtime.agent.started` | Agente iniciado. |
-| `runtime.agent.completed` | Agente concluído. |
-| `runtime.persist.completed` | Persistência concluída. |
-| `runtime.failed` | Falha controlada. |
-
-### Erros
-
-| Código | Condição | Tratamento |
-|---|---|---|
-| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
-| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
-| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
-| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
-| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
-| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
-
-
-
-### Contrato Durável de Estado Transacional
-
-Hosts que utilizam `AgentRuntime` com transações multi-turno DEVEM declarar no `AgentState` os campos `active_transaction` e `last_transaction`. O primeiro é a fonte canônica da transação em andamento e deve sobreviver a checkpoint/resume; o segundo mantém o snapshot da última transação terminal.
-
-```python
-active_transaction: dict[str, Any]
-last_transaction: dict[str, Any]
-```
-
-`selected_tool_call` e `pending_tool_call` são campos auxiliares/compatibilidade e não substituem o latch canônico. Durante `COLLECTING_PARAMETERS`, a retomada da transação e o consumo de parâmetros pendentes têm precedência sobre keyword routing genérico. Uma mudança de intenção só deve interromper a transação quando for inequívoca ou explicitamente solicitada pelo usuário.
-
-O contrato completo, ciclo de vida, precedência de roteamento, checklist e testes regressivos estão em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Runtime recebe GatewayRequest validado.
-- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
-- [ ] Input guardrails executam antes do roteamento.
-- [ ] Router ou Supervisor seleciona rota.
-- [ ] Agent Node executa sem acessar payload bruto de canal.
-- [ ] MCP é acessado por contrato.
-- [ ] RAG é acessado por serviço reutilizável.
-- [ ] Output guardrails executam antes da resposta final.
-- [ ] Judges geram JudgeResult.
-- [ ] Memória e checkpoint são persistidos conforme provider.
-- [ ] Hosts transacionais declaram `active_transaction` e `last_transaction` no `AgentState`.
-- [ ] Durante `COLLECTING_PARAMETERS`, respostas a parâmetros pendentes têm precedência sobre keyword routing genérico.
-- [ ] Erros geram NOC e resposta controlada.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Identity and state contracts
-
-> Consolidated from `specs/SPEC-012-Canonical-Contracts.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Contratos canônicos são estruturas padronizadas usadas para desacoplar canais, gateways, runtime, agentes, tools, LLMs, evaluator e observabilidade.
-
-A plataforma usa contratos para garantir que componentes independentes possam evoluir sem quebrar uns aos outros.
-
-### 2. Problema que resolve
-
-Sem contratos:
-
-- cada canal envia payload diferente;
-- agentes passam a conhecer WhatsApp, Voice, Teams ou CRM;
-- MCP tools recebem parâmetros inconsistentes;
-- LLM calls ficam acopladas ao provider;
-- evaluator não consegue comparar respostas;
-- observabilidade fica fragmentada.
-
-Com contratos:
-
-```text
-Canal → GatewayRequest → Runtime → BusinessContext → ToolInvocation → ToolResult
-```
-
-### 3. Catálogo de contratos
-
-| Contrato | Uso |
-| --- | --- |
-| GatewayRequest | Entrada canônica da plataforma. |
-| ChannelResponse | Resposta canônica ao canal. |
-| BusinessContext | Identidade canônica de negócio. |
-| AgentState | Estado interno do runtime. |
-| Session | Sessão técnica/conversacional. |
-| Checkpoint | Persistência de estado LangGraph. |
-| ToolInvocation | Chamada canônica de tool MCP. |
-| ToolResult | Resposta canônica de tool MCP. |
-| LLMRequest | Chamada canônica ao AI Gateway. |
-| LLMResponse | Resposta canônica do AI Gateway. |
-| EvaluationRun | Execução do evaluator. |
-| EvaluationResult | Resultado de avaliação. |
-| CertificationResult | Resultado de certificação. |
-| EventEnvelope | Envelope de eventos IC/NOC/GRL. |
-
-
-### 4. GatewayRequest
-
-### 4.1. Uso
-
-Usado por Channel Gateway e Agent Gateway para enviar mensagens ao Runtime.
-
-```json
-{
-  "channel": "web",
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "payload": {
-    "message": "Quero consultar minha fatura",
-    "session_id": "session-001",
-    "user_id": "user-001",
-    "message_id": "msg-001",
-    "business_context": {
-      "customer_key": "11999999999",
-      "contract_key": "3000131180",
-      "interaction_key": "301953872",
-      "session_key": "session-001"
-    },
-    "metadata": {
-      "request_id": "req-001",
-      "contract_version": "gateway-request-v1"
-    }
-  }
-}
-```
-
-### 4.2. Campos obrigatórios
-
-- `channel`;
-- `payload.message`;
-- `payload.session_id`;
-- `payload.message_id`;
-- `tenant_id` quando multi-tenant;
-- `agent_id` quando não houver roteamento global.
-
-### 5. ChannelResponse
-
-```json
-{
-  "channel": "web",
-  "session_id": "default:telecom_contas:session-001",
-  "text": "Resposta final do agente.",
-  "metadata": {
-    "tenant_id": "default",
-    "agent_id": "telecom_contas",
-    "route": "billing_agent",
-    "intent": "billing_invoice_explanation",
-    "guardrails": [],
-    "judges": []
-  }
-}
-```
-
-### 6. BusinessContext
-
-### 6.1. Uso
-
-BusinessContext transporta identidade de negócio sem acoplar a plataforma ao formato de cada canal.
-
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
-
-### 6.2. Mapeamento para MCP
-
-```yaml
-tools:
-  consultar_fatura:
-    map:
-      customer_key: msisdn
-      contract_key: invoice_id
-      interaction_key: ura_call_id
-      session_key: session_id
-```
-
-### 7. AgentState
-
-```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    business_context: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    guardrails: list[dict]
-    judges: list[dict]
-```
-
-### 8. ToolInvocation
-
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "tool_name": "consultar_fatura",
-  "arguments": {
-    "msisdn": "11999999999",
-    "invoice_id": "3000131180"
-  },
-  "business_context": {
-    "customer_key": "11999999999",
-    "contract_key": "3000131180"
-  },
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
-```
-
-### 9. ToolResult
-
-```json
-{
-  "tool_name": "consultar_fatura",
-  "ok": true,
-  "data": {
-    "invoice_id": "3000131180",
-    "valor_total": 249.90,
-    "status": "ABERTA"
-  },
-  "cache": {
-    "hit": false,
-    "ttl_seconds": 300
-  },
-  "latency_ms": 140
-}
-```
-
-### 10. LLMRequest
-
-```json
-{
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "profile": "judge",
-  "operation": "judge.response_quality",
-  "messages": [
-    {"role": "system", "content": "Você é um avaliador."},
-    {"role": "user", "content": "Avalie a resposta."}
-  ],
-  "metadata": {
-    "request_id": "req-001",
-    "trace_id": "trace-001"
-  }
-}
-```
-
-### 11. LLMResponse
-
-```json
-{
-  "provider": "oci_openai",
-  "model": "openai.gpt-4.1",
-  "profile": "judge",
-  "content": "Resultado",
-  "usage": {
-    "input_tokens": 1200,
-    "output_tokens": 300,
-    "total_tokens": 1500
-  },
-  "latency_ms": 820
-}
-```
-
-### 12. EvaluationRun
-
-```json
-{
-  "run_id": "eval-001",
-  "agent_id": "telecom_contas",
-  "source": "langfuse",
-  "period_start": "2026-06-18T00:00:00Z",
-  "period_end": "2026-06-19T00:00:00Z",
-  "status": "running"
-}
-```
-
-### 13. EventEnvelope
-
-```json
-{
-  "event_type": "IC.AGENT_COMPLETED",
-  "timestamp": "2026-06-19T12:00:00Z",
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "session_id": "session-001",
-  "trace_id": "trace-001",
-  "payload": {}
-}
-```
-
-### 14. Regras de evolução
-
-- campos novos devem ser opcionais;
-- campos obrigatórios não podem ser removidos dentro da mesma major;
-- mudança semântica exige nova versão;
-- contratos são versionados independentemente.
-
-### 15. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Payload bruto no Runtime | Acopla canais ao core. | Usar GatewayRequest. |
-| Tool recebendo BusinessContext bruto sem mapping | Quebra contrato da tool. | Usar mcp_parameter_mapping.yaml. |
-| LLM direto no agente | Quebra AI Gateway. | Usar LLMRequest/profile. |
-| Campos sem versão | Dificulta migração. | Declarar contract_version. |
-
-
-### 16. Critérios de aceite
-
-- [ ] GatewayRequest documentado e versionado.
-- [ ] ChannelResponse documentado e versionado.
-- [ ] BusinessContext usado por canais e MCP.
-- [ ] ToolInvocation e ToolResult padronizados.
-- [ ] LLMRequest e LLMResponse padronizados.
-- [ ] EvaluationRun e EvaluationResult padronizados.
-- [ ] EventEnvelope usado para IC/NOC/GRL.
-- [ ] Contratos possuem regras de evolução.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/09_llm_rich_response_reasoning.md b/docs/developer/en/09_llm_rich_response_reasoning.md
index 889aee7..c37c83c 100644
--- a/docs/developer/en/09_llm_rich_response_reasoning.md
+++ b/docs/developer/en/09_llm_rich_response_reasoning.md
@@ -1,506 +1,117 @@
-
 ### LLM Rich Response and reasoning_content
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **`ainvoke_response()`, inference metadata and optional `reasoning_content`**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **`ainvoke_response()`, inference metadata, and optional `reasoning_content`**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-`ainvoke_response()`, inference metadata and optional `reasoning_content`.
+`ainvoke_response()`, inference metadata, and optional `reasoning_content`.
 
 ### Consolidated technical content
 
 ### LLM Rich Response and reasoning_content
 
-The LLM abstraction keeps the legacy string-returning API and adds an opt-in structured response for consumers that need inference metadata.
+Guide for using the opt-in structured LLM response API without breaking the legacy `ainvoke()` contract, including `reasoning_content`, usage, model, provider, fallback, and tests.
 
-### Legacy API
+### How to use this document
 
-`ainvoke()` continues to return `str`. Existing agents do not need to change and callers that do not need metadata should keep using it.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### Rich API
+### Rich LLM response API
 
-`ainvoke_response()` returns a structured object containing the final content and, when available, `reasoning_content`, usage, model and provider metadata.
+> Content consolidated from `docs/LLM_RICH_RESPONSE.md`.
 
-`reasoning_content` is optional. The framework never fabricates it. If a provider/model does not expose this field, the value is `None`. The reasoning field remains separate from final user-visible content.
+### Goal
 
-### Backoffice use
+The framework keeps `ainvoke()` as the backward-compatible API, returning only `str`, and adds `ainvoke_response()` for consumers that need additional inference metadata, including `reasoning_content` when the model/provider/API makes it available.
 
-A Backoffice consumer that needs model-decision metadata may opt into `ainvoke_response()` while agent runtime paths that only need final content keep using `ainvoke()`.
+### APIs
 
-### Provider compatibility
+### Legacy API — unchanged
 
-Custom providers that only implement the legacy method continue to work through fallback behavior: the framework wraps the returned text as rich content and leaves reasoning metadata unset. Provider implementations that support richer metadata can override/implement the rich path directly.
+```python
+answer = await llm.ainvoke(messages)
+assert isinstance(answer, str)
+```
 
-### Testing
+No existing agent needs to be changed.
 
-Cover legacy return type, provider with reasoning, provider without reasoning, fallback custom provider, usage/model/provider metadata and failure behavior.
+### New rich API — opt-in
 
-### Source material consolidated
+```python
+response = await llm.ainvoke_response(messages)
+
+answer = response.content
+reasoning = response.reasoning_content
+usage = response.usage
+model = response.model
+provider = response.provider
+```
+
+`reasoning_content` is `str | None`. `None` is the expected behavior when the model, provider, or API does not expose textual reasoning.
+
+### Backoffice
+
+A consumer that previously did:
+
+```python
+answer = await llm.ainvoke(messages)
+template = extract_response(answer)
+```
+
+can instead do:
+
+```python
+response = await llm.ainvoke_response(messages)
+template = extract_response(response.content)
+reasoning_content = response.reasoning_content
+```
+
+Logic that expects text continues to receive `response.content`; reasoning remains separate and does not contaminate response, cache, memory, judges, or guardrails.
+
+### Custom-provider compatibility
+
+`LLMProvider.ainvoke_response()` has a fallback. An external provider that implements only `ainvoke()` continues to work and automatically receives `LLMResponse(content=<texto>)`, with `reasoning_content=None`.
+
+Native providers (`mock`, OpenAI-compatible/OCI OpenAI, and OCI SDK) implement the rich response and attempt to preserve reasoning when present.
+
+### Compatibility guarantees
+
+- `ainvoke()` continues to return `str`.
+- No existing router, judge, RAG, memory, cache, or runtime has been migrated to the new API.
+- `reasoning_content` is never fabricated by the framework.
+- Missing reasoning does not generate an error.
+- Existing telemetry output continues to be the final content, without automatically appending reasoning.
+
+### Tests
+
+Specific tests are in `tests/unit/test_llm_rich_response.py` and verify:
+
+1. a legacy provider that implements only `ainvoke()`;
+2. preservation of the `str` return from `ainvoke()`;
+3. `LLMResponse` return from `ainvoke_response()`;
+4. reasoning through a direct attribute;
+5. reasoning through `model_extra`;
+6. missing reasoning and extraction in OCI SDK format.
+
+### Source files
+
+The files below were consolidated into this manual:
 
 - `docs/LLM_RICH_RESPONSE.md`
 
-### Detailed normative and implementation reference
+### Maintenance rule
 
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### LLM runtime contract context
-
-> Consolidated from `specs/SPEC-002-Agent-Runtime.md`.
-
-### Escopo
-
-O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
-
-### Componentes
-
-| Componente | Responsabilidade |
-|---|---|
-| Workflow Builder | Compila o grafo LangGraph. |
-| State Manager | Mantém o estado de execução. |
-| Session Manager | Resolve sessão e conversation_key. |
-| Memory Manager | Carrega e persiste histórico. |
-| Checkpoint Manager | Persiste estado LangGraph. |
-| Input Guardrail Node | Executa guardrails de entrada. |
-| Router Node | Decide rota/intent. |
-| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
-| Agent Node | Executa agente de domínio. |
-| MCP Client/Router | Executa tools por contrato. |
-| RAG Service | Recupera contexto documental. |
-| Output Supervisor | Revisa resposta antes de saída. |
-| Output Guardrail Node | Executa guardrails de saída. |
-| Judge Node | Avalia resposta. |
-| Persistence Node | Persiste mensagens, memória e checkpoint. |
-
-### State Model
-
-```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    context: dict
-    business_context: dict
-    tool_arguments: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    rag_metadata: dict
-    guardrails: list[dict]
-    judges: list[dict]
-    metadata: dict
-    errors: list[dict]
-```
-
-### Workflow
-
-```mermaid
-flowchart TD
-    A[start] --> B[input_guardrails]
-    B --> C[routing_decision]
-    C --> D[agent_execution]
-    D --> E[output_supervisor]
-    E --> F[output_guardrails]
-    F --> G[judge]
-    G --> H[persist]
-    H --> I[end]
-    C --> J[handoff]
-    J --> C
-```
-
-### Nós
-
-| Nó | Entrada | Saída |
-|---|---|---|
-| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
-| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
-| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
-| `output_supervisor` | `response_text` | `response_text` revisado |
-| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
-| `judge` | `response_text`, evidências | `judges` |
-| `persist` | `state` completo | checkpoint, memória, mensagens |
-
-### Router
-
-```yaml
-routing:
-  mode: router
-  fallback_agent: billing_agent
-  enable_llm_router: false
-  intents:
-    billing_invoice_explanation:
-      route: billing_agent
-      keywords:
-        - fatura
-        - cobrança
-        - boleto
-      mcp_tools:
-        - consultar_fatura
-        - consultar_pagamentos
-```
-
-### Supervisor
-
-```yaml
-supervisor:
-  enabled: true
-  profile: supervisor
-  max_turns: 5
-  handoff_enabled: true
-  fallback_route: support_agent
-```
-
-### Memory
-
-| Provider | Uso |
-|---|---|
-| `memory` | Execução local e testes. |
-| `sqlite` | Desenvolvimento local persistente. |
-| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
-| `autonomous` | Produção com Oracle Autonomous Database. |
-
-### Checkpoints
-
-Checkpoint contém:
-
-```json
-{
-  "conversation_key": "default:telecom_contas:session-001",
-  "checkpoint_id": "ckpt-001",
-  "state": {},
-  "pending_writes": [],
-  "created_at": "2026-06-19T12:00:00Z"
-}
-```
-
-Formato entregue ao LangGraph:
-
-```python
-pending_writes: list[tuple[str, str, object]]
-```
-
-### Business Context
-
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
-
-### Ordem de Prioridade dos Dados
-
-1. `tool_arguments`
-2. `business_context`
-3. `context`
-4. `session.metadata`
-5. `state`
-6. extração complementar do texto
-
-### MCP Integration
-
-```mermaid
-flowchart LR
-    AgentNode --> ToolList[mcp_tools]
-    ToolList --> Mapping[mcp_parameter_mapping.yaml]
-    Mapping --> MCP[MCP Gateway/Router]
-    MCP --> Result[mcp_results]
-```
-
-### RAG Integration
-
-```yaml
-rag:
-  enabled: true
-  namespace_strategy: agent_id
-  top_k: 5
-  profile_generation: rag_generation
-```
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `runtime.started` | Execução iniciada. |
-| `runtime.session.loaded` | Sessão carregada. |
-| `runtime.memory.loaded` | Memória carregada. |
-| `runtime.checkpoint.loaded` | Checkpoint carregado. |
-| `runtime.route.selected` | Rota selecionada. |
-| `runtime.agent.started` | Agente iniciado. |
-| `runtime.agent.completed` | Agente concluído. |
-| `runtime.persist.completed` | Persistência concluída. |
-| `runtime.failed` | Falha controlada. |
-
-### Erros
-
-| Código | Condição | Tratamento |
-|---|---|---|
-| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
-| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
-| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
-| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
-| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
-| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
-
-
-
-### Contrato Durável de Estado Transacional
-
-Hosts que utilizam `AgentRuntime` com transações multi-turno DEVEM declarar no `AgentState` os campos `active_transaction` e `last_transaction`. O primeiro é a fonte canônica da transação em andamento e deve sobreviver a checkpoint/resume; o segundo mantém o snapshot da última transação terminal.
-
-```python
-active_transaction: dict[str, Any]
-last_transaction: dict[str, Any]
-```
-
-`selected_tool_call` e `pending_tool_call` são campos auxiliares/compatibilidade e não substituem o latch canônico. Durante `COLLECTING_PARAMETERS`, a retomada da transação e o consumo de parâmetros pendentes têm precedência sobre keyword routing genérico. Uma mudança de intenção só deve interromper a transação quando for inequívoca ou explicitamente solicitada pelo usuário.
-
-O contrato completo, ciclo de vida, precedência de roteamento, checklist e testes regressivos estão em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Runtime recebe GatewayRequest validado.
-- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
-- [ ] Input guardrails executam antes do roteamento.
-- [ ] Router ou Supervisor seleciona rota.
-- [ ] Agent Node executa sem acessar payload bruto de canal.
-- [ ] MCP é acessado por contrato.
-- [ ] RAG é acessado por serviço reutilizável.
-- [ ] Output guardrails executam antes da resposta final.
-- [ ] Judges geram JudgeResult.
-- [ ] Memória e checkpoint são persistidos conforme provider.
-- [ ] Hosts transacionais declaram `active_transaction` e `last_transaction` no `AgentState`.
-- [ ] Durante `COLLECTING_PARAMETERS`, respostas a parâmetros pendentes têm precedência sobre keyword routing genérico.
-- [ ] Erros geram NOC e resposta controlada.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Compatibility rules
-
-> Consolidated from `specs/SPEC-013-Versioning-and-Compatibility-Model.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Versionamento define como a plataforma evolui sem quebrar projetos existentes. Compatibilidade define quais versões de framework, runtime, gateways, contracts, templates, prompts, tools e evaluator podem operar juntas.
-
-### 2. Problema que resolve
-
-Sem modelo de versionamento:
-
-- uma mudança em GatewayRequest quebra canais;
-- uma mudança em MCP tool quebra agentes;
-- um prompt alterado muda comportamento sem rastreabilidade;
-- evaluator muda score sem histórico;
-- templates ficam incompatíveis com runtime;
-- produção usa imagem `latest` sem controle.
-
-### 3. Semantic Versioning
-
-Formato:
-
-```text
-MAJOR.MINOR.PATCH
-```
-
-Regras:
-
-| Parte | Significado |
-| --- | --- |
-| MAJOR | Mudança incompatível. |
-| MINOR | Nova capacidade compatível. |
-| PATCH | Correção sem mudança de contrato. |
-
-
-### 4. Artefatos versionados
-
-| Artefato | Modelo |
-| --- | --- |
-| agent_framework | SemVer |
-| agent_runtime | SemVer alinhado ao framework |
-| agent_gateway | SemVer + Docker tag |
-| channel_gateway | SemVer + Docker tag |
-| ai_gateway | SemVer + Docker tag |
-| mcp_gateway | SemVer + Docker tag |
-| templates | versão da plataforma |
-| contracts | contract-name-vN |
-| prompts | SemVer |
-| datasets | SemVer |
-| guardrails | SemVer por código |
-| judges | SemVer por judge |
-| mcp_tools | SemVer por tool |
-| evaluator | SemVer |
-| certification_suite | SemVer + ruleset version |
-
-
-### 5. Contract versioning
-
-Exemplos:
-
-```text
-gateway-request-v1
-business-context-v1
-tool-invocation-v1
-llm-request-v1
-```
-
-Permitido na mesma versão major:
-
-- adicionar campos opcionais;
-- adicionar metadata;
-- adicionar enum documentado.
-
-Não permitido:
-
-- remover campo obrigatório;
-- mudar tipo;
-- mudar significado;
-- alterar regra obrigatória.
-
-### 6. Compatibility Matrix
-
-```yaml
-compatibility:
-  - framework: "1.4.x"
-    runtime: "1.4.x"
-    agent_gateway: "1.4.x"
-    supported: true
-  - framework: "1.4.x"
-    runtime: "2.0.x"
-    supported: false
-```
-
-### 7. Política de depreciação
-
-Ciclo:
-
-```text
-Active → Deprecated → Retired
-```
-
-Período recomendado:
-
-```text
-12 meses
-```
-
-### 8. Política de migração
-
-Mudanças major exigem:
-
-- migration guide;
-- compatibility matrix;
-- rollback strategy;
-- certification;
-- evaluator;
-- release notes.
-
-### 9. Estratégia de rollback
-
-Rollback deve considerar:
-
-- imagem Docker;
-- versão do pacote;
-- versão dos YAMLs;
-- versão do contrato;
-- migration de banco;
-- dataset;
-- prompts.
-
-### 10. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Usar latest em produção | Deploy não reprodutível. | Usar tag explícita. |
-| Mudar prompt sem versão | Sem rastreabilidade. | Versionar prompt. |
-| Adicionar campo obrigatório em contrato v1 | Quebra clientes. | Criar v2. |
-| Atualizar evaluator sem baseline | Scores não comparáveis. | Registrar versão e metodologia. |
-
-
-### 11. Critérios de aceite
-
-- [ ] Todos os componentes têm versão.
-- [ ] Contratos têm versão independente.
-- [ ] Matriz de compatibilidade publicada.
-- [ ] Release notes publicadas.
-- [ ] Migrações major possuem guide.
-- [ ] Rollback definido.
-- [ ] Prompts e datasets versionados.
-- [ ] Evaluator e certification registram versão.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/10_performance_cache_and_async_runtime.md b/docs/developer/en/10_performance_cache_and_async_runtime.md
index cc58b61..25f7738 100644
--- a/docs/developer/en/10_performance_cache_and_async_runtime.md
+++ b/docs/developer/en/10_performance_cache_and_async_runtime.md
@@ -1,499 +1,360 @@
-
-### Performance, Cache and Async Runtime
+### Performance, Cache, and Async Runtime
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **concurrency, caching, reduction of LLM calls and cross-loop fixes**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **concurrency, cache, reduction of LLM calls, and cross-loop fixes**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Concurrency, caching, reduction of llm calls and cross-loop fixes.
+Concurrency, cache, reduction of LLM calls, and cross-loop fixes.
 
 ### Consolidated technical content
 
-### Performance, Cache, Concurrency and Asynchronous Runtime
+### Performance, Cache, Concurrency, and Async Runtime
 
-This guide collects optimizations that reduce latency without changing functional semantics.
+Manual for optimizations on the critical MCP, RAG, and Judge path, reduction of LLM calls, deterministic preemption, and cross-loop deadlock correction in sequencing.
 
-### Optimization principles
+### How to use this document
 
-Use deterministic signals before expensive semantic calls when they are reliable; execute independent work concurrently; avoid recomputing retrieval/tool metadata; cache only when correctness allows it; and keep I/O asynchronous without sharing loop-bound primitives incorrectly.
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
 
-### MCP/RAG/Judges
+### MCP, RAG, and Judge optimizations
 
-MCP preparation and repeated metadata operations can be reused where safe. RAG should avoid repeated retrieval/embedding work through configured cache layers. Independent judges can execute concurrently instead of serially.
+> Content consolidated from `docs/PERFORMANCE_OPTIMIZATIONS_MCP_JUDGES_RAG.md`.
 
-Transactional judge rules still override normal sampling optimization: performance must not skip critical evaluation.
+- `mcp_tools` remains an allowlist; only the query selected through `selection_keywords` is executed.
+- `strategy: hybrid` extraction tries a regex `pattern` before the LLM profile.
+- RAG is skipped when successful MCP evidence is sufficient, except for policy/rule questions.
+- `mcp_results` is provided as evidence to the groundedness judge.
+- `judges.yaml` accepts `sample_rate` and `always_run_for_transactional`.
+- Simple structured queries can return a deterministic response without invoking the agent LLM.
 
-### Routing optimization
+### Shift from query to transactional action
 
-Explicit intent-shift signals can preempt the route-continuity LLM. This reduces token consumption and latency while preserving semantic fallback for ambiguous cases.
+Route stickiness is preempted when an explicit keyword configured in `routing.yaml` identifies another intent/agent. Thus, a session in `retail_order_tracking` moves to `retail_support_exchange_return` when it receives requests such as “return order”. In addition, direct responses from read-only tools are blocked when the message contains `selection_keywords` from any registered transactional tool.
+
+Action words remain in `config/tools.yaml`; the runtime does not maintain hardcoded domain aliases.
+
+
+### Deterministic preemption for an explicit intent change
+
+Stickiness does not call a second LLM when the message contains an explicit change that can be recognized deterministically. Multi-token keywords configured in `routing.yaml` accept up to three intermediate tokens while preserving order. Therefore, `cancelar pedido` recognizes `quero cancelar meu pedido`, `cancelar o meu pedido`, and `pode cancelar esse pedido`. In this case the new intent preempts stickiness and the `keyword_match_strategy=ordered_tokens` metadata makes the decision auditable. Messages with no explicit signal continue using route stickiness normally.
 
 ### Cross-loop deadlock fix
 
-Sequence generation/observability previously could wait on synchronization primitives associated with another event loop. The fix removes cross-loop waiting and keeps sequencing safe for asynchronous runtime and tests that create multiple loops.
+> Content consolidated from `Documentacao/FIX_DEADLOCK_SEQUENCE_CROSS_LOOP.md`.
 
-### Validation
+### Problem
 
-Performance tests should measure latency and call counts, not only functional output. Regression coverage should include concurrent judges, cached/uncached RAG behavior, MCP reuse paths, deterministic routing preemption and observer/sequence calls across separate event loops.
+The synchronous `agent_framework.observer.event()` API could be called from a worker thread with no active event loop. In that case, the previous implementation ran `asyncio.run(aevent(...))`, creating a temporary new event loop. At the same time, `analytics/tim_sequence.py` shared global `asyncio.Lock` instances (`_mongo_index_lock` and `_memory_lock`) across calls that could come from different event loops.
 
-### Source material consolidated
+On the first Mongo operation, `_ensure_mongo_ttl_index_once()` held `_mongo_index_lock` while creating the TTL index. Contention from another loop could leave the second call waiting indefinitely.
+
+### Applied changes
+
+1. `observer.py`
+   - removed `asyncio.run()` from the synchronous `event()` path;
+   - added a dedicated reusable event loop for synchronous calls;
+   - cross-thread submission uses `asyncio.run_coroutine_threadsafe()`;
+   - best-effort loop shutdown when the process terminates.
+
+2. `analytics/tim_sequence.py`
+   - `_mongo_index_lock`: `asyncio.Lock` -> `threading.Lock`;
+   - `_memory_lock`: `asyncio.Lock` -> `threading.Lock`;
+   - TTL-index initialization moved to a synchronous function protected by a thread lock and called through `asyncio.to_thread()`;
+   - the in-memory fallback counter uses a short thread-safe critical section.
+
+3. Tests
+   - `tests/test_observer_cross_loop_deadlock_fix.py` validates:
+     - multiple worker threads using `event()` share the same synchronous observer loop;
+     - in-memory sequence remains monotonic across independent event loops;
+     - TTL-index creation happens only once under cross-loop contention.
+
+### Validation performed
+
+```bash
+PYTHONPATH=libs/agent_framework/src pytest -q tests/test_observer_cross_loop_deadlock_fix.py
+```
+
+Result: `3 passed`.
+
+The full repository suite has pre-existing/independent failures unrelated to this change, including collection conflicts for `test_long_term_memory.py`, static template paths, and checkpoint/workflow tests. Those items were not changed by this fix.
+
+### Operational performance features
+
+> Content consolidated from `Documentacao/README_MAX_OPERACIONAL.md`.
+
+This version adds the operational adjustments that were missing to bring the framework closer to the FIRST production standard.
+
+### Adjustments included in this version
+
+### 1. Langfuse Enterprise Adapter
+
+New module:
+
+```text
+agent_framework/observability/langfuse_enterprise.py
+```
+
+Includes an adapter compatible with Langfuse SDKs v2/v3 for:
+
+- trace updates;
+- trace scoring/evaluation;
+- prompt registry when supported by the SDK;
+- isolation of Langfuse API differences.
+
+### 2. Persistent Token and Cost Accounting
+
+New package:
+
+```text
+agent_framework/billing/
+```
+
+Includes:
+
+- `UsageRecord`
+- `SQLiteUsageRepository`
+- `OracleUsageRepository`
+- `create_usage_repository(settings)`
+
+The LLM provider now records automatically:
+
+- `prompt_tokens`
+- `completion_tokens`
+- `cached_tokens`
+- `total_tokens`
+- `cost_usd`
+- `cost_brl`
+- `tenant_id`
+- `agent_id`
+- `session_id`
+- `message_id`
+
+New endpoint:
+
+```http
+GET /debug/usage
+GET /debug/usage?tenant_id=default
+GET /debug/usage?session_id=<id>
+```
+
+### 3. Operational RAG Service
+
+New module:
+
+```text
+agent_framework/rag/rag_service.py
+```
+
+Includes:
+
+- `RagService.add_documents()`
+- `RagService.retrieve()`
+- `RagResult.as_prompt_context()`
+- telemetry for latency, document count, top scores, and graph.
+
+### 4. New configuration
+
+Variable added:
+
+```env
+USAGE_REPOSITORY_PROVIDER=sqlite
+```
+
+Values:
+
+```text
+sqlite
+oracle
+autonomous
+```
+
+### 5. Local operational compatibility
+
+By default, usage accounting uses SQLite even when everything else is in memory. This makes local testing possible without Oracle.
+
+### Quick test
+
+```bash
+cd agent_template_backend
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Test a message:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"text":"teste","user_id":"u1","session_id":"s1"}}'
+```
+
+Check usage/cost:
+
+```bash
+curl http://localhost:8000/debug/usage
+```
+
+### To run closer to a production pattern
+
+```env
+SESSION_REPOSITORY_PROVIDER=sqlite
+MEMORY_REPOSITORY_PROVIDER=sqlite
+CHECKPOINT_REPOSITORY_PROVIDER=sqlite
+USAGE_REPOSITORY_PROVIDER=sqlite
+CACHE_BACKEND_PROVIDER=sqlite
+VECTOR_STORE_PROVIDER=sqlite
+ENABLE_LANGFUSE=true
+LANGFUSE_HOST=http://localhost:3000
+LANGFUSE_PUBLIC_KEY=...
+LANGFUSE_SECRET_KEY=...
+```
+
+For Autonomous Database:
+
+```env
+SESSION_REPOSITORY_PROVIDER=oracle
+MEMORY_REPOSITORY_PROVIDER=oracle
+CHECKPOINT_REPOSITORY_PROVIDER=oracle
+USAGE_REPOSITORY_PROVIDER=oracle
+CACHE_BACKEND_PROVIDER=oracle
+VECTOR_STORE_PROVIDER=oracle
+GRAPH_STORE_PROVIDER=oracle
+ADB_USER=...
+ADB_PASSWORD=...
+ADB_DSN=...
+ADB_WALLET_LOCATION=...
+ADB_TABLE_PREFIX=AGENTFW
+```
+
+### Final cache, RAG, and telemetry adjustments
+
+> Content consolidated from `Documentacao/README_FIRST_MAX_OPERATIONAL_FIXES.md`.
+
+This version fixes the gaps identified in the comparison against FIRST.
+
+### Applied fixes
+
+### 1. Operational LangGraph checkpoint
+
+The workflow no longer compiles directly with `MemorySaver()`. The following adapter was created:
+
+```text
+agent_framework/checkpoints/langgraph_saver.py
+```
+
+It connects LangGraph to the framework's configured repository:
+
+- `memory`
+- `sqlite`
+- `oracle` / `autonomous`
+
+In the workflow:
+
+```python
+builder.compile(checkpointer=create_langgraph_checkpointer(self.settings))
+```
+
+### 2. LangGraph telemetry wrapping actual execution
+
+A node wrapper was added to the workflow:
+
+```python
+self._node("billing_agent", self.billing_agent)
+```
+
+This way the `langgraph.node.*` span/event wraps actual node execution, not just an empty block.
+
+Events emitted:
+
+- `langgraph.node.started`
+- `langgraph.node.completed`
+- `langgraph.node.failed`
+- `langgraph.edge.selected`
+
+### 3. RAG integrated into agents
+
+Agents now receive `RagService` and use retrieved context in the prompt:
+
+- BillingAgent
+- ProductAgent
+- OrdersAgent
+- SupportAgent
+
+RAG uses:
+
+- `VECTOR_STORE_PROVIDER=memory|sqlite|oracle|autonomous`
+- `GRAPH_STORE_PROVIDER=memory|oracle|autonomous`
+- `RAG_TOP_K`
+
+### 4. Cache integrated into agent runtime
+
+The following mixin was created:
+
+```text
+agent_template_backend/app/agents/runtime.py
+```
+
+It adds:
+
+- standardized RAG retrieval;
+- cache key for LLM calls;
+- hit/miss with telemetry;
+- distributed cache through `create_cache(settings)`.
+
+### 5. Unit tests
+
+The following directory was created:
+
+```text
+tests/unit
+```
+
+Initial coverage:
+
+- cache;
+- SSE;
+- RAG;
+- checkpoint saver;
+- LangGraph telemetry;
+- agent runtime;
+- static workflow verification;
+- main imports.
+
+Local validation performed:
+
+```text
+12 passed
+```
+
+### How to test
+
+```bash
+cd projeto_agent_framework_first_ready
+pip install -r agent_template_backend/requirements.txt
+pytest -q tests/unit
+```
+
+### Source files
+
+The files below were consolidated into this manual:
 
 - `docs/PERFORMANCE_OPTIMIZATIONS_MCP_JUDGES_RAG.md`
 - `Documentacao/FIX_DEADLOCK_SEQUENCE_CROSS_LOOP.md`
-- operational notes in `Documentacao/README_MAX_OPERACIONAL.md` and `README_FIRST_MAX_OPERATIONAL_FIXES.md`
+- `Documentacao/README_MAX_OPERACIONAL.md`
+- `Documentacao/README_FIRST_MAX_OPERATIONAL_FIXES.md`
 
-### Detailed normative and implementation reference
+### Maintenance rule
 
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### Runtime execution requirements
-
-> Consolidated from `specs/SPEC-002-Agent-Runtime.md`.
-
-### Escopo
-
-O Agent Runtime executa o ciclo de vida conversacional do agente. A execução inclui normalização de contexto, estado LangGraph, memória, checkpoint, roteamento, supervisor, guardrails, MCP, RAG, LLM, judges, persistência e resposta final.
-
-### Componentes
-
-| Componente | Responsabilidade |
-|---|---|
-| Workflow Builder | Compila o grafo LangGraph. |
-| State Manager | Mantém o estado de execução. |
-| Session Manager | Resolve sessão e conversation_key. |
-| Memory Manager | Carrega e persiste histórico. |
-| Checkpoint Manager | Persiste estado LangGraph. |
-| Input Guardrail Node | Executa guardrails de entrada. |
-| Router Node | Decide rota/intent. |
-| Supervisor Node | Decide handoff ou próximo agente quando habilitado. |
-| Agent Node | Executa agente de domínio. |
-| MCP Client/Router | Executa tools por contrato. |
-| RAG Service | Recupera contexto documental. |
-| Output Supervisor | Revisa resposta antes de saída. |
-| Output Guardrail Node | Executa guardrails de saída. |
-| Judge Node | Avalia resposta. |
-| Persistence Node | Persiste mensagens, memória e checkpoint. |
-
-### State Model
-
-```python
-class AgentState(TypedDict, total=False):
-    user_text: str
-    sanitized_input: str
-    response_text: str
-    tenant_id: str
-    agent_id: str
-    channel: str
-    session_id: str
-    conversation_key: str
-    message_id: str
-    route: str
-    intent: str
-    context: dict
-    business_context: dict
-    tool_arguments: dict
-    mcp_tools: list[str]
-    mcp_results: list[dict]
-    rag_context: str
-    rag_metadata: dict
-    guardrails: list[dict]
-    judges: list[dict]
-    metadata: dict
-    errors: list[dict]
-```
-
-### Workflow
-
-```mermaid
-flowchart TD
-    A[start] --> B[input_guardrails]
-    B --> C[routing_decision]
-    C --> D[agent_execution]
-    D --> E[output_supervisor]
-    E --> F[output_guardrails]
-    F --> G[judge]
-    G --> H[persist]
-    H --> I[end]
-    C --> J[handoff]
-    J --> C
-```
-
-### Nós
-
-| Nó | Entrada | Saída |
-|---|---|---|
-| `input_guardrails` | `user_text`, `context` | `sanitized_input`, `guardrails` |
-| `routing_decision` | `sanitized_input`, `business_context` | `route`, `intent`, `mcp_tools` |
-| `agent_execution` | `state` completo | `response_text`, `mcp_results`, `rag_metadata` |
-| `output_supervisor` | `response_text` | `response_text` revisado |
-| `output_guardrails` | `response_text` | `response_text`, `guardrails` |
-| `judge` | `response_text`, evidências | `judges` |
-| `persist` | `state` completo | checkpoint, memória, mensagens |
-
-### Router
-
-```yaml
-routing:
-  mode: router
-  fallback_agent: billing_agent
-  enable_llm_router: false
-  intents:
-    billing_invoice_explanation:
-      route: billing_agent
-      keywords:
-        - fatura
-        - cobrança
-        - boleto
-      mcp_tools:
-        - consultar_fatura
-        - consultar_pagamentos
-```
-
-### Supervisor
-
-```yaml
-supervisor:
-  enabled: true
-  profile: supervisor
-  max_turns: 5
-  handoff_enabled: true
-  fallback_route: support_agent
-```
-
-### Memory
-
-| Provider | Uso |
-|---|---|
-| `memory` | Execução local e testes. |
-| `sqlite` | Desenvolvimento local persistente. |
-| `mongodb` | Checkpoint e histórico em ambiente distribuído. |
-| `autonomous` | Produção com Oracle Autonomous Database. |
-
-### Checkpoints
-
-Checkpoint contém:
-
-```json
-{
-  "conversation_key": "default:telecom_contas:session-001",
-  "checkpoint_id": "ckpt-001",
-  "state": {},
-  "pending_writes": [],
-  "created_at": "2026-06-19T12:00:00Z"
-}
-```
-
-Formato entregue ao LangGraph:
-
-```python
-pending_writes: list[tuple[str, str, object]]
-```
-
-### Business Context
-
-```yaml
-business_context:
-  customer_key: "11999999999"
-  contract_key: "3000131180"
-  interaction_key: "301953872"
-  account_key: null
-  resource_key: null
-  session_key: "session-001"
-  metadata:
-    source_channel: web
-```
-
-### Ordem de Prioridade dos Dados
-
-1. `tool_arguments`
-2. `business_context`
-3. `context`
-4. `session.metadata`
-5. `state`
-6. extração complementar do texto
-
-### MCP Integration
-
-```mermaid
-flowchart LR
-    AgentNode --> ToolList[mcp_tools]
-    ToolList --> Mapping[mcp_parameter_mapping.yaml]
-    Mapping --> MCP[MCP Gateway/Router]
-    MCP --> Result[mcp_results]
-```
-
-### RAG Integration
-
-```yaml
-rag:
-  enabled: true
-  namespace_strategy: agent_id
-  top_k: 5
-  profile_generation: rag_generation
-```
-
-### Eventos
-
-| Evento | Descrição |
-|---|---|
-| `runtime.started` | Execução iniciada. |
-| `runtime.session.loaded` | Sessão carregada. |
-| `runtime.memory.loaded` | Memória carregada. |
-| `runtime.checkpoint.loaded` | Checkpoint carregado. |
-| `runtime.route.selected` | Rota selecionada. |
-| `runtime.agent.started` | Agente iniciado. |
-| `runtime.agent.completed` | Agente concluído. |
-| `runtime.persist.completed` | Persistência concluída. |
-| `runtime.failed` | Falha controlada. |
-
-### Erros
-
-| Código | Condição | Tratamento |
-|---|---|---|
-| `RUNTIME_INVALID_REQUEST` | GatewayRequest inválido | 422 |
-| `RUNTIME_ROUTE_NOT_FOUND` | Nenhuma rota elegível | fallback ou resposta controlada |
-| `RUNTIME_CHECKPOINT_ERROR` | Falha em checkpoint | retry ou stateless conforme config |
-| `RUNTIME_MEMORY_ERROR` | Falha em memória | retry ou resposta controlada |
-| `RUNTIME_AGENT_ERROR` | Falha no agente | NOC + fallback |
-| `RUNTIME_TIMEOUT` | Timeout geral | resposta controlada |
-
-
-
-### Contrato Durável de Estado Transacional
-
-Hosts que utilizam `AgentRuntime` com transações multi-turno DEVEM declarar no `AgentState` os campos `active_transaction` e `last_transaction`. O primeiro é a fonte canônica da transação em andamento e deve sobreviver a checkpoint/resume; o segundo mantém o snapshot da última transação terminal.
-
-```python
-active_transaction: dict[str, Any]
-last_transaction: dict[str, Any]
-```
-
-`selected_tool_call` e `pending_tool_call` são campos auxiliares/compatibilidade e não substituem o latch canônico. Durante `COLLECTING_PARAMETERS`, a retomada da transação e o consumo de parâmetros pendentes têm precedência sobre keyword routing genérico. Uma mudança de intenção só deve interromper a transação quando for inequívoca ou explicitamente solicitada pelo usuário.
-
-O contrato completo, ciclo de vida, precedência de roteamento, checklist e testes regressivos estão em [`docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md`](../docs/TRANSACTION_STATE_DEVELOPER_GUIDE.md).
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Runtime recebe GatewayRequest validado.
-- [ ] State contém tenant_id, agent_id, session_id, conversation_key, route e intent.
-- [ ] Input guardrails executam antes do roteamento.
-- [ ] Router ou Supervisor seleciona rota.
-- [ ] Agent Node executa sem acessar payload bruto de canal.
-- [ ] MCP é acessado por contrato.
-- [ ] RAG é acessado por serviço reutilizável.
-- [ ] Output guardrails executam antes da resposta final.
-- [ ] Judges geram JudgeResult.
-- [ ] Memória e checkpoint são persistidos conforme provider.
-- [ ] Hosts transacionais declaram `active_transaction` e `last_transaction` no `AgentState`.
-- [ ] Durante `COLLECTING_PARAMETERS`, respostas a parâmetros pendentes têm precedência sobre keyword routing genérico.
-- [ ] Erros geram NOC e resposta controlada.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Operational performance and SRE requirements
-
-> Consolidated from `specs/SPEC-020-Operational-Readiness-and-SRE-Model.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Operational Readiness define os requisitos mínimos para operar a Agent Platform OCI em produção com confiabilidade, observabilidade, capacidade de resposta a incidentes e recuperação.
-
-### 2. Componentes operados
-
-- Agent Gateway;
-- Channel Gateway;
-- Agent Runtime;
-- AI Gateway;
-- MCP Gateway;
-- MCP Servers;
-- Evaluator;
-- bancos/repositórios;
-- Langfuse/OTEL;
-- Redis/Mongo/ADB quando usados.
-
-### 3. Health e readiness
-
-Endpoints mínimos:
-
-```text
-GET /health
-GET /ready
-GET /version
-```
-
-### 4. SLOs
-
-| Componente | Latência | Disponibilidade |
-| --- | --- | --- |
-| Agent Gateway | p95 < 1s | 99.5% |
-| Agent Runtime | p95 < 5s | 99.0% |
-| AI Gateway | p95 < 10s | 99.0% |
-| MCP Gateway | p95 < 2s | 99.0% |
-| Evaluator | janela batch | execução diária |
-
-
-### 5. Métricas
-
-- requests_total;
-- request_latency_ms;
-- errors_total;
-- active_sessions;
-- llm_tokens_total;
-- llm_cost_estimated;
-- mcp_tool_calls_total;
-- guardrail_blocks_total;
-- judge_scores;
-- evaluator_scores.
-
-### 6. Dashboards
-
-Dashboards mínimos:
-
-- Platform Overview;
-- Runtime;
-- Gateway;
-- AI Gateway;
-- MCP Gateway;
-- Guardrails;
-- Evaluator;
-- Cost/Usage;
-- Incidents.
-
-### 7. Alertas
-
-| Alerta | Condição |
-| --- | --- |
-| HighErrorRate | 5xx acima do limite. |
-| LatencySLOBreach | p95 acima do SLO. |
-| LLMProviderDown | Falhas consecutivas no provider. |
-| MCPTimeoutSpike | Aumento de timeout MCP. |
-| GuardrailSpike | Aumento anômalo de bloqueios. |
-| EvaluatorFailed | Run falhou. |
-
-
-### 8. Runbooks
-
-Runbook deve conter:
-
-- sintoma;
-- impacto;
-- consultas;
-- dashboards;
-- logs;
-- ações;
-- rollback;
-- escalonamento.
-
-### 9. Incident management
-
-Fluxo:
-
-```mermaid
-flowchart LR
-    Detect[Detect] --> Triage[Triage]
-    Triage --> Mitigate[Mitigate]
-    Mitigate --> Recover[Recover]
-    Recover --> Postmortem[Postmortem]
-```
-
-### 10. Capacidade
-
-Avaliar:
-
-- QPS;
-- sessões simultâneas;
-- tokens/minuto;
-- chamadas MCP/minuto;
-- latência de provider;
-- uso de memória;
-- storage de checkpoints.
-
-### 11. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Sem readiness | Tráfego antes do app estar pronto. | Implementar /ready. |
-| Sem alertas MCP | Falha silenciosa. | Criar alertas por tool. |
-| Sem runbook | MTTR alto. | Criar runbooks por incidente. |
-| Sem custo LLM | Sem controle financeiro. | Registrar tokens/custos. |
-
-
-### 12. Production readiness checklist
-
-- [ ] Health checks ativos.
-- [ ] Readiness checks ativos.
-- [ ] Logs estruturados.
-- [ ] Métricas exportadas.
-- [ ] Traces exportados.
-- [ ] Dashboards criados.
-- [ ] Alertas configurados.
-- [ ] Runbooks disponíveis.
-- [ ] Rollback validado.
-- [ ] SLOs definidos.
-- [ ] Capacidade estimada.
-- [ ] Incident process definido.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/11_observability_persistence_and_operational_readiness.md b/docs/developer/en/11_observability_persistence_and_operational_readiness.md
index dc1b659..a44be6f 100644
--- a/docs/developer/en/11_observability_persistence_and_operational_readiness.md
+++ b/docs/developer/en/11_observability_persistence_and_operational_readiness.md
@@ -1,824 +1,689 @@
-
-### Observability, Persistence and Operational Readiness
+### Observability, Persistence, and Operational Readiness
 
 ### How to use this manual
 
 This is a **specialized reference manual**. It does not replace the main tutorial.
 
-- To build an agent end to end, use [`README_en.md`](../../../README_en.md).
-- Use this document when implementing, deep-diving or troubleshooting **telemetry, IC/NOC/GRL, correlation, sequencing, persistence and operational diagnostics**.
-- Historical examples consolidated here must be interpreted against the current framework API.
-- If documentation differs, the current code and root README take precedence.
+- To create an agent from start to finish, use [`README_en.md`](../../../README_en.md).
+- Use this document when you need to implement, deepen, or diagnose **telemetry, IC/NOC/GRL, correlation, sequencing, persistence, and operational diagnostics**.
+- Historical examples consolidated here should be read in light of the framework's current API.
+- In case of divergence, the code for the version and the current `README_en.md` take precedence.
 
 ### Relationship with the main tutorial
 
-`README_en.md` introduces this capability as part of the normal development flow. This manual consolidates details previously spread across `docs/`, `Documentacao/`, release notes, validation records and specialized guides.
+The `README_en.md` presents this capability in the normal development flow. This manual brings together details that were distributed across `docs/`, `Documentacao/`, release notes, validations, and specialized guides.
 
-Its purpose is to answer **“how does this feature work in depth and how do I troubleshoot it?”** without becoming a second copy of the main tutorial.
+The goal here is to answer **“how does this feature work in depth and how do I solve problems with it?”**, without turning this file into a second copy of the main tutorial.
 
 ### Scope
 
-Telemetry, ic/noc/grl, correlation, sequencing, persistence and operational diagnostics.
+Telemetry, IC/NOC/GRL, correlation, sequencing, persistence, and operational diagnostics.
 
 ### Consolidated technical content
 
-### Observability, Persistence and Operational Readiness
+### Observability, Persistence, and Operational Readiness
 
-This guide consolidates the FIRST-ready operational capabilities that turn the framework into an observable, persistent platform rather than a stateless demo.
+Consolidated guide to FIRST-ready capabilities: end-to-end correlation, Langfuse, OpenTelemetry, observable SSE, Oracle persistence, token/cost accounting, cache, and LangGraph telemetry.
+
+### How to use this document
+
+This is the consolidated development document for this subject. It brings together architecture, configuration, examples, runtime behavior, compatibility, tests, and troubleshooting that were previously distributed across several files. Source sections were preserved when they provided distinct technical details; release notes were incorporated as current behavior or correction history.
+
+### FIRST-ready foundation and observability
+
+> Content consolidated from `Documentacao/README_FIRST_READY.md`.
+
+This version preserves the `meu_projeto_agent_framework` architecture and adds the operational patterns found in the FIRST project.
+
+### Added features
+
+1. **SSE following the FIRST pattern**
+   - `GET /gateway/events/{session_id}` for a `text/event-stream`.
+   - `POST /gateway/message/sse` to process a message while emitting SSE events.
+   - Events: `connected`, `flow.start`, `session.upserted`, `message.received`, `workflow.started`, `workflow.completed`, `message.responded`, `flow.end`.
+   - Keepalive configurable through `SSE_KEEPALIVE_SECONDS`.
+   - Per-session lock to prevent concurrency within the same conversation.
+   - Event replay through `Last-Event-ID` or the `last_event_id` query parameter.
+
+2. **Session and message persistence**
+   - Implemented `sqlite` provider, runnable locally.
+   - `SESSION_REPOSITORY_PROVIDER=sqlite`.
+   - `MEMORY_REPOSITORY_PROVIDER=sqlite`.
+   - Local tables: `agent_sessions`, `agent_messages`.
+   - Idempotency by `message_id`.
+
+3. **Persistent checkpoint**
+   - Implemented `sqlite` provider for the workflow's final checkpoint.
+   - `CHECKPOINT_REPOSITORY_PROVIDER=sqlite`.
+   - Read endpoint: `GET /sessions/{session_id}/checkpoint`.
+
+4. **Message history**
+   - Endpoint: `GET /sessions/{session_id}/messages`.
+   - History is used as conversational memory before invoking LangGraph.
+
+5. **Cache**
+   - New module `agent_framework.cache.cache`.
+   - Supports local in-memory cache and Redis when `ENABLE_REDIS_CACHE=true`.
+
+6. **RAG / Vector Store**
+   - `agent_framework.rag.vector_store` now includes `InMemoryVectorStore`, `SQLiteVectorStore`, and the `AutonomousVectorStore` contract.
+   - The SQLite version uses local lexical search for development.
+   - The contract allows replacement by Oracle Vector Search without changing the application layer.
+
+7. **Observability**
+   - Preserves existing Langfuse integration.
+   - Adds gateway/SSE/workflow events with `session_id`, `agent_id`, `tenant_id`, `message_id`, route, and intent.
+
+### Resulting architecture
+
+```text
+Browser
+  |-- POST /gateway/message/sse
+  |-- GET  /gateway/events/{session_id}
+        |
+FastAPI Template Backend
+        |
+ChannelGateway
+        |
+SessionRepository + MessageHistory + CheckpointRepository
+        |
+LangGraph AgentWorkflow
+        |
+Guardrails -> Router/Supervisor -> Agent -> Output Guardrails -> Judges
+        |
+Telemetry / Langfuse / OCI Streaming
+```
+
+### How to run locally
+
+```bash
+cd agent_template_backend
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e ../agent_framework
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Frontend:
+
+```bash
+cd agent_frontend
+python -m http.server 3000
+```
+
+Open:
+
+```text
+http://localhost:3000
+```
+
+### Main variables
+
+```env
+SESSION_REPOSITORY_PROVIDER=sqlite
+MEMORY_REPOSITORY_PROVIDER=sqlite
+CHECKPOINT_REPOSITORY_PROVIDER=sqlite
+VECTOR_STORE_PROVIDER=sqlite
+SQLITE_DB_PATH=./data/agent_framework.db
+ENABLE_SSE=true
+SSE_KEEPALIVE_SECONDS=15
+ENABLE_MESSAGE_IDEMPOTENCY=true
+```
+
+### Test with curl
+
+Normal message:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"text":"teste","message":"teste","session_id":"s1","user_id":"u1","message_id":"m1"}}'
+```
+
+Message with SSE:
+
+```bash
+curl -N http://localhost:8000/gateway/events/s1
+```
+
+In another terminal:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message/sse \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"text":"teste","message":"teste","session_id":"s1","user_id":"u1","message_id":"m2"}}'
+```
+
+History:
+
+```bash
+curl http://localhost:8000/sessions/s1/messages
+```
+
+Checkpoint:
+
+```bash
+curl http://localhost:8000/sessions/s1/checkpoint
+```
+
+### Important note
+
+The added version is locally executable with SQLite. The `AutonomousSessionRepository`, `DatabaseMessageHistory`, `AutonomousCheckpointRepository`, and `AutonomousVectorStore` classes preserve the Oracle Autonomous Database contract, but in this delivery they use SQLite as the local backend so the project can run and be tested without Oracle infrastructure.
+
+### FIRST-style Observability evolution
+
+This version adds an enterprise observability layer to the framework while keeping reusable components inside `agent_framework`.
+
+### Added components
+
+```text
+agent_framework/observability/
+├── context.py             # ContextVar: request_id, session_id, user_id, tenant_id, agent_id, channel, ura_call_id, workflow_id, message_id
+├── telemetry.py           # Facade central: span, event, generation, rag_event, cache_event, checkpoint_event
+├── event_bus.py           # Event bus interno para plugar logs, SSE, OCI Streaming, Elastic, Phoenix etc.
+├── otel.py                # OpenTelemetry opcional via OTLP
+├── workflow_events.py     # workflow.started, node.started, node.completed, edge.selected, workflow.failed
+├── guardrail_events.py    # guardrail.<CODE>.evaluated e guardrail.<CODE>.blocked
+├── judge_events.py        # judge.<NAME>.evaluated
+├── streaming_events.py    # sse.connected, sse.keepalive, sse.event.emitted
+└── decorators.py          # decorator @traced para classes do framework
+```
 
 ### End-to-end correlation
 
-Every request should preserve correlation across channel/gateway, selected agent, LangGraph execution, guardrails, judges, MCP calls and final response. Tenant, agent, session, request/trace and transaction identifiers should remain consistent across emitted events.
+Each HTTP call creates or propagates `x-request-id`, and the message flow links:
 
-### Langfuse and OpenTelemetry
+```text
+request_id → tenant_id → agent_id → session_id → user_id → channel → message_id → workflow_id
+```
 
-Langfuse provides LLM/trace-oriented observability while OpenTelemetry supports vendor-neutral traces/metrics/log integration. The runtime adapters should wrap the real execution path rather than emitting synthetic telemetry disconnected from the actual graph/tool call.
+The context uses `ContextVar`, so it works across async calls, FastAPI, LangGraph, and LLM providers.
 
-### LangGraph telemetry
+### Langfuse
 
-Graph execution should be traced around the real nodes/edges so route decisions, agent execution and failures are visible. SSE responses must preserve correlation even though delivery is streamed.
+Enable in `.env`:
 
-### Persistent state
+```env
+ENABLE_LANGFUSE=true
+LANGFUSE_PUBLIC_KEY=pk-lf-...
+LANGFUSE_SECRET_KEY=sk-lf-...
+LANGFUSE_HOST=http://localhost:3000
+```
 
-Enterprise configurations may use Oracle Autonomous Database for durable platform data. Checkpoints, sessions, long-term memory and analytics have different retention/consistency requirements and should not be collapsed into a single logical table just because they share a database technology.
+The framework records:
 
-### Token and cost accounting
+```text
+Trace de conversa
+├── http.request
+├── agent.gateway_message
+├── workflow.langgraph.ainvoke
+├── workflow.input_guardrails
+│   └── guardrail.<CODE>.evaluated / blocked
+├── workflow.routing_decision
+├── workflow.agent.<agent>
+│   └── generation.<model>
+├── workflow.output_guardrails
+├── workflow.judge
+│   └── judge.<NAME>.evaluated
+├── workflow.supervisor_review
+├── workflow.persist
+└── sse.event.emitted / sse.keepalive
+```
 
-Model usage metadata can be persisted/aggregated for operational and financial visibility. Rich provider usage metadata should be preferred when available; missing provider fields must not be invented.
+### OpenTelemetry
 
-### Cache
+Enable in `.env`:
 
-Enterprise cache reduces repeated work for safe reusable operations. Cache keys must include the identity/context necessary to prevent cross-agent or cross-tenant leakage.
+```env
+ENABLE_OTEL=true
+OTEL_SERVICE_NAME=agent-framework-template
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/traces
+```
 
-### Operational validation
+With this configuration, the same spans are exported through OTLP to Elastic, Grafana Tempo, Jaeger, Collector, or another compatible backend.
 
-Before production, validate failure paths, telemetry delivery, disabled-observability behavior, persistence restart, SSE correlation, tool latency/error spans, guardrail/judge events and token/cost accounting. Also validate the Global Supervisor configuration if that routing mode is used.
+### Observable SSE
 
-### Source material consolidated
+`SSEHub` now records events for:
+
+- opened connection;
+- event replay;
+- emitted event;
+- keepalive;
+- per-session lock during message processing.
+
+### Guardrails and Judges
+
+In addition to aggregate events (`guardrails.input.completed`, `judges.completed`), each individual decision generates its own telemetry:
+
+```text
+guardrail.MSK.evaluated
+guardrail.OOS.blocked
+judge.response_quality.evaluated
+judge.groundedness.evaluated
+```
+
+### Extension to other backends
+
+The `Telemetry.event_bus` class allows new handlers to be plugged in without changing the workflow. Example:
+
+```python
+async def enviar_para_elastic(event):
+    ...
+
+telemetry.event_bus.subscribe(enviar_para_elastic)
+```
+
+
+---
+
+### Complete FIRST Enterprise evolution
+
+This version received the components that were missing to bring the framework closer to the operational standard of the FIRST project:
+
+### Oracle Autonomous Database persistence
+
+Real Oracle providers were added:
+
+- `OracleSessionRepository`
+- `OracleMessageHistory`
+- `OracleCheckpointRepository`
+- `OracleCache`
+- `OracleVectorStore`
+- `OracleGraphStore`
+- `OracleStore`
+
+Tables are created automatically with configurable `ADB_TABLE_PREFIX`:
+
+- `<PREFIX>_AGENT_SESSION`
+- `<PREFIX>_AGENT_MESSAGE`
+- `<PREFIX>_WORKFLOW_CHECKPOINT`
+- `<PREFIX>_WORKFLOW_CHECKPOINT_WRITE`
+- `<PREFIX>_WORKFLOW_CHECKPOINT_BLOB`
+- `<PREFIX>_SSE_EVENT`
+- `<PREFIX>_CACHE_ENTRY`
+- `<PREFIX>_RAG_DOCUMENT`
+- `<PREFIX>_GRAPH_EDGE`
+
+### Oracle configuration
+
+```env
+SESSION_REPOSITORY_PROVIDER=oracle
+MEMORY_REPOSITORY_PROVIDER=oracle
+CHECKPOINT_REPOSITORY_PROVIDER=oracle
+CACHE_BACKEND_PROVIDER=oracle
+VECTOR_STORE_PROVIDER=oracle
+GRAPH_STORE_PROVIDER=oracle
+SSE_STORE_PROVIDER=oracle
+
+ADB_USER=ADMIN
+ADB_PASSWORD=***
+ADB_DSN=meu_adb_high
+ADB_WALLET_LOCATION=/path/wallet
+ADB_WALLET_PASSWORD=***
+ADB_TABLE_PREFIX=AGENTFW
+```
+
+### Enterprise SSE
+
+SSE now includes:
+
+- per-session lock (`SessionLockManager`)
+- configurable keepalive
+- replay through `Last-Event-ID`
+- event persistence in SQLite or Oracle
+- connection, replay, keepalive, and disconnection telemetry
+
+Endpoint:
+
+```text
+GET /gateway/events/{session_id}?last_event_id=123
+```
+
+### LangGraph Deep Telemetry
+
+`LangGraphDeepTelemetry` was added with events:
+
+- `langgraph.node.started`
+- `langgraph.node.completed`
+- `langgraph.node.failed`
+- `langgraph.edge.selected`
+
+These events are sent to Event Bus, Langfuse, and OpenTelemetry when enabled.
+
+### Token and Cost Accounting
+
+The following were added:
+
+- `TokenUsageCollector`
+- `CostTracker`
+- calculation of `prompt_tokens`, `completion_tokens`, `cached_tokens`, `total_tokens`
+- calculation of `cost_usd` and `cost_brl`
+
+Optional configuration:
+
+```env
+USD_BRL_RATE=5.0
+MODEL_PRICES_JSON={"openai.gpt-4.1":{"input_per_1m":"2.00","output_per_1m":"8.00"}}
+```
+
+### Enterprise Cache
+
+Cache is now layered:
+
+```text
+L1: InMemory
+L2: Redis, SQLite ou Oracle
+```
+
+Configuration:
+
+```env
+ENABLE_REDIS_CACHE=true
+REDIS_URL=redis://localhost:6379/0
+```
+
+or:
+
+```env
+CACHE_BACKEND_PROVIDER=oracle
+```
+
+### Oracle 23ai RAG
+
+`OracleVectorStore` was added, with support for a `VECTOR` column and `VECTOR_DISTANCE()` when an embedding provider is connected.  
+Without an embedding provider, it keeps a lexical fallback for local development.
+
+`OracleGraphStore` was also added with an edge table, ready to evolve to PGQL/Property Graph.
+
+### Langfuse
+
+Each LLM call now generates a `generation` with:
+
+- input
+- output
+- model
+- provider
+- token usage
+- cost metadata
+
+In addition, workflow, guardrail, judge, RAG, cache, checkpoint, SSE, and LangGraph spans are published through the same Event Bus.
+
+### Enterprise Plus extensions
+
+> Content consolidated from `Documentacao/README_FIRST_ENTERPRISE_PLUS.md`.
+
+This version evolves the framework in the four requested areas:
+
+1. **Complete Langfuse Enterprise**
+   - `Telemetry.span()` with trace/session/user/metadata/tags.
+   - `Telemetry.generation()` with `usage`, token/cost metadata, and Langfuse v2/v3 compatibility.
+   - `Telemetry.score()` for judges/evaluations.
+   - Arbitrary events are recorded as safe spans to avoid `Unknown observation type` in Langfuse.
+
+2. **Complete Token/Cost Accounting**
+   - `TokenUsageCollector` supports `prompt_tokens`, `completion_tokens`, `cached_tokens`, `reasoning_tokens`, and `total_tokens`.
+   - Per-model pricing table through `MODEL_PRICES_JSON`.
+   - USD→BRL conversion through `USD_BRL_RATE`.
+   - Persistence in `UsageRepository` and `/debug/usage` endpoint.
+
+3. **Distributed Redis**
+   - `DistributedCache`: L1 memory + L2 Redis/SQLite/Oracle.
+   - `RedisCache` with `redis.asyncio` when available and sync fallback.
+   - Namespace through `CACHE_KEY_PREFIX`.
+   - Cache hit/miss/set/delete telemetry.
+
+4. **Real Oracle Vector + PGQL**
+   - `OracleVectorStore` uses `VECTOR_DISTANCE(..., COSINE)` and `TO_VECTOR()` in Oracle 23ai.
+   - Automatically attempts to create a vector index when supported.
+   - `OracleGraphStore` uses `GRAPH_NODE` and `GRAPH_EDGE` tables.
+   - Supports Property Graph creation and `GRAPH_TABLE`/PGQL queries, with SQL fallback.
+
+The SSE duplication problem caused by replay + live queue was also fixed using `max_replayed_id` control in `SSEHub.subscribe()`.
+
+### Tests
+
+```bash
+PYTHONPATH=agent_framework/src pytest -q tests/unit
+```
+
+Result validated in this generation:
+
+```text
+17 passed
+```
+
+### Security
+
+The `.env` files were sanitized so they do not contain real keys. Configure your credentials locally before using OCI/Langfuse.
+
+### Delta to FIRST standard
+
+> Content consolidated from `Documentacao/README_FIRST_ENTERPRISE_DELTA.md`.
+
+This version fixes the priorities identified in the comparison with FIRST:
+
+1. Real Oracle Session Repository
+2. Real Oracle Message History
+3. Real Oracle LangGraph Checkpoint Repository
+4. LangGraph Deep Telemetry
+5. Token Accounting
+6. Cost Accounting
+7. SSE Session Lock
+8. SSE Replay Buffer
+9. SSE KeepAlive
+10. Recovery through Last-Event-ID
+11. Redis Provider and Distributed Cache
+12. Oracle Vector Provider
+13. Oracle Graph Provider
+14. RAG Telemetry
+15. Langfuse Generation Tracking
+16. Compatible OpenTelemetry/Event Bus
+17. Preserved OCI Streaming Exporter
+
+Domain logic remains generic; the framework does not copy FIRST-specific billing rules.
+
+### Maximum operations and accounting
+
+> Content consolidated from `Documentacao/README_MAX_OPERACIONAL.md`.
+
+This version adds the operational adjustments that were missing to bring the framework closer to the FIRST production standard.
+
+### Adjustments included in this version
+
+### 1. Langfuse Enterprise Adapter
+
+New module:
+
+```text
+agent_framework/observability/langfuse_enterprise.py
+```
+
+Includes an adapter compatible with Langfuse SDKs v2/v3 for:
+
+- trace updates;
+- trace scoring/evaluation;
+- prompt registry when supported by the SDK;
+- isolation of Langfuse API differences.
+
+### 2. Persistent Token and Cost Accounting
+
+New package:
+
+```text
+agent_framework/billing/
+```
+
+Includes:
+
+- `UsageRecord`
+- `SQLiteUsageRepository`
+- `OracleUsageRepository`
+- `create_usage_repository(settings)`
+
+The LLM provider now records automatically:
+
+- `prompt_tokens`
+- `completion_tokens`
+- `cached_tokens`
+- `total_tokens`
+- `cost_usd`
+- `cost_brl`
+- `tenant_id`
+- `agent_id`
+- `session_id`
+- `message_id`
+
+New endpoint:
+
+```http
+GET /debug/usage
+GET /debug/usage?tenant_id=default
+GET /debug/usage?session_id=<id>
+```
+
+### 3. Operational RAG Service
+
+New module:
+
+```text
+agent_framework/rag/rag_service.py
+```
+
+Includes:
+
+- `RagService.add_documents()`
+- `RagService.retrieve()`
+- `RagResult.as_prompt_context()`
+- telemetry for latency, document count, top scores, and graph.
+
+### 4. New configuration
+
+Variable added:
+
+```env
+USAGE_REPOSITORY_PROVIDER=sqlite
+```
+
+Values:
+
+```text
+sqlite
+oracle
+autonomous
+```
+
+### 5. Local operational compatibility
+
+By default, usage accounting uses SQLite even when everything else is in memory. This makes it possible to test locally without Oracle.
+
+### Quick test
+
+```bash
+cd agent_template_backend
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```
+
+Test a message:
+
+```bash
+curl -X POST http://localhost:8000/gateway/message \
+  -H 'Content-Type: application/json' \
+  -d '{"channel":"web","payload":{"text":"teste","user_id":"u1","session_id":"s1"}}'
+```
+
+Check usage/cost:
+
+```bash
+curl http://localhost:8000/debug/usage
+```
+
+### To run closer to a production pattern
+
+```env
+SESSION_REPOSITORY_PROVIDER=sqlite
+MEMORY_REPOSITORY_PROVIDER=sqlite
+CHECKPOINT_REPOSITORY_PROVIDER=sqlite
+USAGE_REPOSITORY_PROVIDER=sqlite
+CACHE_BACKEND_PROVIDER=sqlite
+VECTOR_STORE_PROVIDER=sqlite
+ENABLE_LANGFUSE=true
+LANGFUSE_HOST=http://localhost:3000
+LANGFUSE_PUBLIC_KEY=...
+LANGFUSE_SECRET_KEY=...
+```
+
+For Autonomous Database:
+
+```env
+SESSION_REPOSITORY_PROVIDER=oracle
+MEMORY_REPOSITORY_PROVIDER=oracle
+CHECKPOINT_REPOSITORY_PROVIDER=oracle
+USAGE_REPOSITORY_PROVIDER=oracle
+CACHE_BACKEND_PROVIDER=oracle
+VECTOR_STORE_PROVIDER=oracle
+GRAPH_STORE_PROVIDER=oracle
+ADB_USER=...
+ADB_PASSWORD=...
+ADB_DSN=...
+ADB_WALLET_LOCATION=...
+ADB_TABLE_PREFIX=AGENTFW
+```
+
+### Complementary supervisor validation
+
+> Content consolidated from `docs/docs_GLOBAL_SUPERVISOR_VALIDATION.txt`.
+
+VALIDATION - GLOBAL SUPERVISOR
+
+Implemented changes:
+
+1. Framework
+- agent_framework.global_supervisor.models
+- agent_framework.global_supervisor.config
+- agent_framework.global_supervisor.session_store
+- agent_framework.global_supervisor.router
+- agent_framework.global_supervisor.client
+
+2. New service
+- agent_gateway/app/main.py
+- agent_gateway/app/settings.py
+- agent_gateway/config/backends.yaml
+- agent_gateway/README.md
+- agent_gateway/Dockerfile
+- agent_gateway/docs/ARQUITETURA_GLOBAL_SUPERVISOR.md
+
+3. Docker Compose
+- agent-gateway service added on port 8010.
+
+Validations performed:
+
+- python3 -m compileall -q agent_framework/src/agent_framework/global_supervisor agent_gateway/app
+  Result: OK
+
+- Hybrid-routing smoke test:
+  Input 1: "My bill is too high" -> billing
+  Input 2: "and this amount?" on the same session_id -> billing via active_backend
+  Result: OK
+
+- FastAPI app import smoke test:
+  from app.main import app, registry, router
+  Result: OK
+
+Note:
+- The gateway SSE proxy was left as a future step. The `/gateway/message/sse` endpoint already routes and forwards as a normal message; for end-to-end SSE, a proxy from `/gateway/events/{session_id}` to the active backend can be implemented.
+
+### Source files
+
+The files below were consolidated into this manual:
 
 - `Documentacao/README_FIRST_READY.md`
 - `Documentacao/README_FIRST_ENTERPRISE_PLUS.md`
 - `Documentacao/README_FIRST_ENTERPRISE_DELTA.md`
 - `Documentacao/README_MAX_OPERACIONAL.md`
-- Global Supervisor validation records under `docs/`
+- `docs/docs_GLOBAL_SUPERVISOR_VALIDATION.txt`
 
-### Detailed normative and implementation reference
+### Maintenance rule
 
-The sections below preserve the detailed English project specifications and implementation guides relevant to this capability. They are included here so a developer does not need to reconstruct the behavior from separate documents.
-
-### Observability specification
-
-> Consolidated from `specs/SPEC-007-Observability.md`.
-
-### Escopo
-
-Observabilidade cobre logs, métricas, traces, eventos IC/NOC/GRL, Langfuse, OpenTelemetry, dashboards, alertas e evidências operacionais.
-
-### Correlação
-
-Campos obrigatórios:
-
-```text
-request_id
-trace_id
-session_id
-conversation_key
-tenant_id
-agent_id
-channel
-message_id
-route
-intent
-```
-
-### Logs
-
-Formato:
-
-```json
-{
-  "timestamp": "2026-06-19T12:00:00Z",
-  "level": "INFO",
-  "service": "agent-runtime",
-  "event": "runtime.route.selected",
-  "tenant_id": "default",
-  "agent_id": "telecom_contas",
-  "session_id": "default:telecom_contas:session-001",
-  "trace_id": "trace-001",
-  "route": "billing_agent",
-  "intent": "billing_invoice_explanation"
-}
-```
-
-### Traces
-
-```mermaid
-flowchart TD
-    T[conversation trace] --> A[gateway.received]
-    T --> B[channel.normalized]
-    T --> C[runtime.started]
-    T --> D[guardrails.input]
-    T --> E[routing]
-    T --> F[agent.execution]
-    F --> G[mcp.tool]
-    F --> H[llm.generation]
-    T --> I[guardrails.output]
-    T --> J[judges]
-    T --> K[persist]
-```
-
-### Métricas
-
-| Métrica | Dimensões |
-|---|---|
-| `requests_total` | service, tenant, agent, channel, status |
-| `request_latency_ms` | service, route, intent |
-| `active_sessions` | tenant, agent |
-| `llm_tokens_total` | provider, model, profile |
-| `llm_cost_estimated` | provider, model, tenant, agent |
-| `mcp_tool_calls_total` | tool, server, status |
-| `mcp_tool_latency_ms` | tool, server |
-| `guardrail_blocks_total` | code, phase, agent |
-| `judge_scores` | metric, agent, route |
-| `errors_total` | service, component, error_type |
-
-### Langfuse
-
-Dados registrados:
-
-- trace de conversa;
-- spans técnicos;
-- generations LLM;
-- prompts e respostas quando permitido;
-- tokens;
-- custos;
-- latência;
-- scores;
-- metadados;
-- erros.
-
-### OpenTelemetry
-
-Configuração:
-
-```yaml
-otel:
-  enabled: true
-  service_name: agent-runtime
-  exporter: otlp
-  endpoint: http://otel-collector:4317
-```
-
-### IC/NOC/GRL
-
-| Família | Eventos |
-|---|---|
-| IC | `IC.GATEWAY_RECEIVED`, `IC.AGENT_STARTED`, `IC.AGENT_COMPLETED` |
-| NOC | `NOC.RUNTIME_FAILED`, `NOC.MCP_TIMEOUT`, `NOC.LLM_FAILED` |
-| GRL | `GRL.INPUT_BLOCKED`, `GRL.OUTPUT_BLOCKED`, `GRL.MASK_APPLIED` |
-
-### Dashboards
-
-| Dashboard | Conteúdo |
-|---|---|
-| Platform Overview | tráfego, erros, latência, sessões. |
-| Agent Runtime | rotas, intents, memória, checkpoints. |
-| LLM Usage | tokens, custo, latência, provider/model. |
-| MCP Operations | chamadas, erros, cache, latência. |
-| Guardrails | bloqueios, observe-only, códigos. |
-| Evals | scores, trends, regressões. |
-| Channels | tráfego por canal, erros, retries. |
-
-### Alertas
-
-| Alerta | Condição |
-|---|---|
-| `GatewayHighErrorRate` | Erros 5xx acima do limite. |
-| `RuntimeLatencyHigh` | p95 acima do SLO. |
-| `LLMProviderUnavailable` | falhas consecutivas de provider. |
-| `MCPToolTimeoutSpike` | aumento de timeouts. |
-| `GuardrailBlockSpike` | aumento anômalo de bloqueios. |
-| `EvaluatorRunFailed` | run batch falhou. |
-| `CheckpointFailure` | falha persistente em checkpoint. |
-
-### Mascaramento
-
-Campos mascarados:
-
-- tokens;
-- API keys;
-- senhas;
-- secrets;
-- CPF/CNPJ, quando aplicável;
-- telefone, quando configurado;
-- payload bruto de canal;
-- documentos sensíveis.
-
-### Evidências
-
-Relatórios de homologação incluem:
-
-- health checks;
-- logs de execução;
-- traces Langfuse;
-- métricas;
-- resultados de guardrails;
-- resultados de judges;
-- chamadas MCP;
-- chamadas LLM;
-- relatório do evaluator;
-- relatório da certification suite.
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Todos os serviços emitem logs estruturados.
-- [ ] Trace correlaciona gateway, runtime, MCP, LLM, guardrails e judges.
-- [ ] Langfuse recebe traces quando habilitado.
-- [ ] OTEL exporta spans quando habilitado.
-- [ ] Métricas mínimas estão disponíveis.
-- [ ] Dashboards estão definidos.
-- [ ] Alertas estão definidos.
-- [ ] Segredos e PII são mascarados.
-- [ ] Evaluator consome dados observáveis.
-- [ ] Certification Suite gera evidências.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Operational readiness and SRE model
-
-> Consolidated from `specs/SPEC-020-Operational-Readiness-and-SRE-Model.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Operational Readiness define os requisitos mínimos para operar a Agent Platform OCI em produção com confiabilidade, observabilidade, capacidade de resposta a incidentes e recuperação.
-
-### 2. Componentes operados
-
-- Agent Gateway;
-- Channel Gateway;
-- Agent Runtime;
-- AI Gateway;
-- MCP Gateway;
-- MCP Servers;
-- Evaluator;
-- bancos/repositórios;
-- Langfuse/OTEL;
-- Redis/Mongo/ADB quando usados.
-
-### 3. Health e readiness
-
-Endpoints mínimos:
-
-```text
-GET /health
-GET /ready
-GET /version
-```
-
-### 4. SLOs
-
-| Componente | Latência | Disponibilidade |
-| --- | --- | --- |
-| Agent Gateway | p95 < 1s | 99.5% |
-| Agent Runtime | p95 < 5s | 99.0% |
-| AI Gateway | p95 < 10s | 99.0% |
-| MCP Gateway | p95 < 2s | 99.0% |
-| Evaluator | janela batch | execução diária |
-
-
-### 5. Métricas
-
-- requests_total;
-- request_latency_ms;
-- errors_total;
-- active_sessions;
-- llm_tokens_total;
-- llm_cost_estimated;
-- mcp_tool_calls_total;
-- guardrail_blocks_total;
-- judge_scores;
-- evaluator_scores.
-
-### 6. Dashboards
-
-Dashboards mínimos:
-
-- Platform Overview;
-- Runtime;
-- Gateway;
-- AI Gateway;
-- MCP Gateway;
-- Guardrails;
-- Evaluator;
-- Cost/Usage;
-- Incidents.
-
-### 7. Alertas
-
-| Alerta | Condição |
-| --- | --- |
-| HighErrorRate | 5xx acima do limite. |
-| LatencySLOBreach | p95 acima do SLO. |
-| LLMProviderDown | Falhas consecutivas no provider. |
-| MCPTimeoutSpike | Aumento de timeout MCP. |
-| GuardrailSpike | Aumento anômalo de bloqueios. |
-| EvaluatorFailed | Run falhou. |
-
-
-### 8. Runbooks
-
-Runbook deve conter:
-
-- sintoma;
-- impacto;
-- consultas;
-- dashboards;
-- logs;
-- ações;
-- rollback;
-- escalonamento.
-
-### 9. Incident management
-
-Fluxo:
-
-```mermaid
-flowchart LR
-    Detect[Detect] --> Triage[Triage]
-    Triage --> Mitigate[Mitigate]
-    Mitigate --> Recover[Recover]
-    Recover --> Postmortem[Postmortem]
-```
-
-### 10. Capacidade
-
-Avaliar:
-
-- QPS;
-- sessões simultâneas;
-- tokens/minuto;
-- chamadas MCP/minuto;
-- latência de provider;
-- uso de memória;
-- storage de checkpoints.
-
-### 11. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Sem readiness | Tráfego antes do app estar pronto. | Implementar /ready. |
-| Sem alertas MCP | Falha silenciosa. | Criar alertas por tool. |
-| Sem runbook | MTTR alto. | Criar runbooks por incidente. |
-| Sem custo LLM | Sem controle financeiro. | Registrar tokens/custos. |
-
-
-### 12. Production readiness checklist
-
-- [ ] Health checks ativos.
-- [ ] Readiness checks ativos.
-- [ ] Logs estruturados.
-- [ ] Métricas exportadas.
-- [ ] Traces exportados.
-- [ ] Dashboards criados.
-- [ ] Alertas configurados.
-- [ ] Runbooks disponíveis.
-- [ ] Rollback validado.
-- [ ] SLOs definidos.
-- [ ] Capacidade estimada.
-- [ ] Incident process definido.
-
-### Deployment operational requirements
-
-> Consolidated from `specs/SPEC-008-Deployment.md`.
-
-### Escopo
-
-Deployment cobre empacotamento, CI/CD, Kubernetes/OKE, Docker, secrets, autenticação OCI, health checks, rollback e operação dos componentes.
-
-### Componentes Deployáveis
-
-| Componente | Artefato |
-|---|---|
-| Agent Gateway | Docker image + Kubernetes Deployment |
-| Channel Gateway | Docker image + Kubernetes Deployment |
-| AI Gateway | Docker image + Kubernetes Deployment |
-| MCP Gateway | Docker image + Kubernetes Deployment |
-| Agent Backend | Docker image + Kubernetes Deployment |
-| MCP Server | Docker image + Kubernetes Deployment |
-| Evaluator API | Docker image + Kubernetes Deployment |
-| Evaluator Batch | Kubernetes CronJob |
-| Frontend Demo | Docker image opcional |
-
-### Pipeline
-
-```mermaid
-flowchart LR
-    A[Commit] --> B[Lint]
-    B --> C[Type Check]
-    C --> D[Unit Tests]
-    D --> E[Contract Tests]
-    E --> F[Security Scan]
-    F --> G[Build Wheel]
-    G --> H[Build Images]
-    H --> I[Publish]
-    I --> J[Deploy Dev]
-    J --> K[Smoke Tests]
-    K --> L[Certification]
-    L --> M[Deploy HML/Prod]
-```
-
-### Stages
-
-```yaml
-stages:
-  - validate
-  - lint
-  - type_check
-  - unit_test
-  - contract_test
-  - security_scan
-  - build_package
-  - build_image
-  - publish
-  - deploy_dev
-  - smoke_test
-  - certification
-  - deploy_hml
-  - deploy_prod
-```
-
-### Kubernetes Deployment
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: agent-runtime
-  labels:
-    app: agent-runtime
-    component: runtime
-spec:
-  replicas: 2
-  selector:
-    matchLabels:
-      app: agent-runtime
-  template:
-    metadata:
-      labels:
-        app: agent-runtime
-    spec:
-      serviceAccountName: agent-runtime-sa
-      containers:
-        - name: agent-runtime
-          image: registry/agent-runtime:1.0.0
-          ports:
-            - containerPort: 8000
-          envFrom:
-            - configMapRef:
-                name: agent-runtime-config
-            - secretRef:
-                name: agent-runtime-secrets
-          readinessProbe:
-            httpGet:
-              path: /ready
-              port: 8000
-          livenessProbe:
-            httpGet:
-              path: /health
-              port: 8000
-```
-
-### Service
-
-```yaml
-apiVersion: v1
-kind: Service
-metadata:
-  name: agent-runtime
-spec:
-  selector:
-    app: agent-runtime
-  ports:
-    - port: 8000
-      targetPort: 8000
-```
-
-### OCI Authentication
-
-| Ambiente | Modo |
-|---|---|
-| Local | `config_file` |
-| Local com endpoint OpenAI-Compatible | API key |
-| OCI Compute | `instance_principal` |
-| OKE | `workload_identity` ou `resource_principal` |
-| Testes | `mock` |
-
-### Variáveis
-
-```env
-LLM_PROVIDER=oci_sdk
-OCI_AUTH_MODE=workload_identity
-ENABLE_LANGFUSE=true
-ENABLE_OTEL=true
-SESSION_REPOSITORY_PROVIDER=autonomous
-MEMORY_REPOSITORY_PROVIDER=autonomous
-CHECKPOINT_REPOSITORY_PROVIDER=autonomous
-```
-
-### Secrets
-
-| Secret | Uso |
-|---|---|
-| `LANGFUSE_PUBLIC_KEY` | Langfuse |
-| `LANGFUSE_SECRET_KEY` | Langfuse |
-| `OCI_GENAI_API_KEY` | OCI OpenAI-Compatible |
-| `ADB_PASSWORD` | Autonomous Database |
-| `MCP_BACKEND_TOKEN` | Integrações MCP |
-| `OTEL_AUTH_TOKEN` | Exportador OTEL, se aplicável |
-
-### Health Checks
-
-| Endpoint | Uso |
-|---|---|
-| `/health` | Processo vivo. |
-| `/ready` | Pronto para tráfego. |
-| `/version` | Versão de build. |
-| `/debug/env` | Ambiente sem segredos, quando habilitado. |
-
-### Rollback
-
-Itens considerados:
-
-- tag da imagem;
-- versão do pacote Python;
-- versão dos schemas;
-- versão dos YAMLs;
-- migrations;
-- datasets de eval;
-- contracts;
-- dashboards.
-
-### Smoke Tests
-
-```bash
-curl -f http://agent-runtime:8000/health
-curl -f http://agent-gateway:9000/health
-curl -f http://mcp-gateway:8300/health
-curl -f http://ai-gateway:9100/health
-```
-
-### Certification Stage
-
-A pipeline executa:
-
-- health checks;
-- contrato GatewayRequest;
-- roteamento;
-- MCP invoke;
-- LLM mock/real conforme ambiente;
-- guardrails;
-- judges;
-- memória/checkpoint;
-- relatório JSON/HTML.
-
-
-### Requisitos Não Funcionais
-
-| Categoria | Requisito |
-|---|---|
-| Disponibilidade | Componentes deployáveis expõem `/health` e `/ready`. |
-| Escalabilidade | Apps stateless escalam horizontalmente. Estado conversacional fica em repositórios externos. |
-| Segurança | Segredos são fornecidos por secret store ou Kubernetes Secrets. |
-| Observabilidade | Logs, métricas e traces usam correlação por request_id, trace_id, session_id, tenant_id e agent_id. |
-| Auditabilidade | Decisões de rota, guardrail, judge, MCP e LLM são rastreáveis. |
-| Portabilidade | Execução suportada em local, Docker Compose e Kubernetes/OKE. |
-| Configuração | Comportamento variável é controlado por `.env` e YAML versionado. |
-
-
-### Critérios de Aceite
-
-- [ ] Cada app possui Dockerfile.
-- [ ] Cada app possui manifest Kubernetes.
-- [ ] CI executa lint, type check e testes.
-- [ ] Contract tests validam contratos principais.
-- [ ] Security scan executa antes do publish.
-- [ ] Secrets não são versionados.
-- [ ] Workload Identity está configurado em OKE.
-- [ ] Health/readiness/liveness estão ativos.
-- [ ] Smoke tests rodam após deploy.
-- [ ] Rollback está documentado.
-
-
-### Glossário
-
-| Termo | Definição |
-|---|---|
-| Agent Platform | Plataforma composta por runtime, gateways, evaluator, templates, contratos e componentes operacionais. |
-| Agent Framework | Biblioteca/core reutilizável com contratos, guardrails, judges, memória, telemetria, providers e utilitários. |
-| Agent Runtime | Motor de execução de agentes baseado em LangGraph, estado, sessão, memória, checkpoints, roteamento e ciclo de vida. |
-| Agent Gateway | Aplicação deployável de entrada, roteamento e orquestração entre backends/agentes. |
-| Channel Gateway | Aplicação ou módulo de normalização de payloads de canais para GatewayRequest. |
-| AI Gateway | Aplicação de governança, roteamento e abstração de chamadas LLM/embedding. |
-| MCP Gateway | Aplicação de governança e roteamento de tools MCP. |
-| Evaluator | Camada de avaliação online/offline, regressão e certificação. |
-| Business Context | Conjunto de chaves canônicas de negócio: customer_key, contract_key, interaction_key, account_key, resource_key e session_key. |
-
-### Release management and CI/CD
-
-> Consolidated from `specs/SPEC-017-Release-Management-and-CICD.md`.
-
-### Agent Platform OCI
-
-Version: 1.0.0
-
-
----
-
-### Padrão de leitura
-
-Cada SPEC está organizada para servir tanto como contrato arquitetural quanto como guia prático de adoção.
-
-A estrutura usada é:
-
-1. Conceito.
-2. Problema que resolve.
-3. Quando usar.
-4. Quando não usar.
-5. Arquitetura.
-6. Implementação.
-7. Exemplos.
-8. Erros comuns.
-9. Critérios de aceite.
-
----
-
-
-### 1. Conceito
-
-Release management define como mudanças entram na plataforma, são testadas, empacotadas, publicadas, promovidas e auditadas.
-
-CI/CD automatiza validações e reduz risco operacional.
-
-### 2. Pipeline padrão
-
-```mermaid
-flowchart LR
-    C[Commit] --> L[Lint]
-    L --> TC[Type Check]
-    TC --> UT[Unit Tests]
-    UT --> IT[Integration Tests]
-    IT --> CT[Contract Tests]
-    CT --> SS[Security Scan]
-    SS --> B[Build]
-    B --> P[Publish]
-    P --> DD[Deploy Dev]
-    DD --> ST[Smoke Tests]
-    ST --> CERT[Certification]
-    CERT --> HML[Deploy HML]
-    HML --> PROD[Deploy Prod]
-```
-
-### 3. Stages
-
-| Stage | Função |
-| --- | --- |
-| validate | Validação inicial de estrutura. |
-| lint | Estilo e erros simples. |
-| type_check | Tipos e contratos Python. |
-| unit_test | Testes unitários. |
-| integration_test | Integrações locais. |
-| contract_test | Contratos JSON/YAML/API. |
-| security_scan | Dependências, secrets e imagens. |
-| build_package | Wheel/package. |
-| build_image | Imagem Docker. |
-| publish | Registry/artifacts. |
-| deploy_dev | Ambiente dev. |
-| smoke_test | Health e chamadas básicas. |
-| certification | Certification Suite. |
-| deploy_hml | Homologação. |
-| deploy_prod | Produção. |
-
-
-### 4. Artefatos de release
-
-- imagem Docker;
-- pacote Python;
-- release notes;
-- matriz de compatibilidade;
-- migration guide quando necessário;
-- evaluator report;
-- certification report;
-- SBOM quando aplicável;
-- evidência de scan;
-- changelog.
-
-### 5. Exemplo de pipeline
-
-```yaml
-stages:
-  - lint
-  - test
-  - contract
-  - security
-  - build
-  - publish
-  - deploy
-  - certification
-```
-
-### 6. Gates
-
-| Gate | Quando aplica |
-| --- | --- |
-| Architecture Gate | Mudanças estruturais, contratos, runtime, gateways. |
-| Security Gate | Segredos, identidade, dados sensíveis, MCP externo. |
-| Quality Gate | Testes, evaluator, certification. |
-| Operations Gate | Dashboards, alertas, runbook, rollback. |
-
-
-### 7. Estratégia de rollback
-
-Rollback deve restaurar:
-
-- imagem anterior;
-- configuração anterior;
-- contrato anterior;
-- prompt anterior;
-- dataset anterior quando necessário;
-- migration de banco quando aplicável.
-
-### 8. Erros comuns
-
-| Erro | Impacto | Correção |
-| --- | --- | --- |
-| Deploy sem certification | Risco funcional. | Rodar certification no pipeline. |
-| Sem release notes | Sem rastreabilidade. | Publicar release notes. |
-| Sem contract tests | Quebra integração. | Adicionar testes de contrato. |
-| Sem rollback | Risco operacional. | Definir estratégia de rollback. |
-
-
-### 9. Critérios de aceite
-
-- [ ] Pipeline executa lint, type check e testes.
-- [ ] Contract tests executam.
-- [ ] Security scan executa.
-- [ ] Imagem Docker gerada.
-- [ ] Artifacts publicados.
-- [ ] Smoke tests executados.
-- [ ] Certification executada.
-- [ ] Release notes publicadas.
-- [ ] Rollback definido.
-- [ ] Evidências arquivadas.
+New fixes or evolutions for this subject should update this consolidated document. Release notes may continue to exist as history, but they should not be required to understand or implement the feature.
diff --git a/docs/developer/en/INDEX_DEVELOPER_GUIDE.md b/docs/developer/en/INDEX_DEVELOPER_GUIDE.md
index b07208b..e88a907 100644
--- a/docs/developer/en/INDEX_DEVELOPER_GUIDE.md
+++ b/docs/developer/en/INDEX_DEVELOPER_GUIDE.md
@@ -1,129 +1,133 @@
-
 ### Developer Index — Agent Framework OCI
 
 ### How to use this documentation
 
 The documentation has three clear levels:
 
-1. **Main tutorial:** [`README_en.md`](../../../README_en.md) — build, configure, run and test an agent end to end.
-2. **Architecture:** [01 — Architecture and Concepts](./01_architecture_and_concepts.md) — components, boundaries and implementation placement.
-3. **Specialized references:** manuals `02` through `11` — deep implementation and troubleshooting by capability.
+1. **Main tutorial:** [`README_en.md`](README_en.md) — creation, configuration, execution, and testing of an agent from start to finish.
+2. **Architecture:** [01 — Architecture and Concepts](docs/developer/en/01_architecture_and_concepts.md) — components, responsibilities, and where to implement each concern.
+3. **Specialized references:** manuals `02` through `11` — in-depth implementation and troubleshooting by capability.
 
-If you are creating a new agent, start with the main README.
+If you are starting a new agent, begin with `README_en.md`.
 
 If something is not working, use **Search by problem** below.
 
 ### Search by problem
 
-| Problem / question | Usually involves | Go to |
+| Problem / question | What is usually involved | Where to look |
 |---|---|---|
-| Framework selects the wrong agent/intent | routing, intents, thresholds, deterministic/LLM mode | [Routing and Stickiness](./02_routing_stickiness_and_intent_shift.md) |
-| Agent stays stuck on the same subject | route stickiness, intent shift, handoff | [Routing and Stickiness](./02_routing_stickiness_and_intent_shift.md) |
-| A parameter answer is mistaken for a new intent | transaction precedence, parameter extraction | [Transactional Workflows](./03_transaction_workflows_and_state.md) |
-| Transaction keeps asking for the same parameter | transaction state, extractor, schema | [Transactional Workflows](./03_transaction_workflows_and_state.md) and [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
-| “yes/no” confirmation does not continue the flow | confirmation state | [Transactional Workflows](./03_transaction_workflows_and_state.md) |
-| A closed transaction reappears | old checkpoint vs active transaction | [Transactional Workflows](./03_transaction_workflows_and_state.md) and [LTM/Checkpoint](./08_long_term_memory_and_checkpoint.md) |
-| System claims an operation ran but there is no evidence | MCP results, `COMPLETED`, transaction judges | [Transactional Workflows](./03_transaction_workflows_and_state.md) and [Guardrails/Judges](./06_guardrails_judges_and_transaction_evaluation.md) |
-| A tool is missing | tools config, MCP catalog/discovery | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
-| MCP Server is missing from catalog | registration, manifest/discovery, MCP Gateway | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) and [Gateways](./05_agent_gateway_mcp_gateway_and_auth.md) |
-| Tool parameters are wrong | schema, mapping, BusinessContext, extraction | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
-| Transactional tool executes without confirmation | policy, `require_confirmation` | [MCP/Tools](./04_mcp_integration_tools_and_policies.md) |
-| 401 between gateway/backend/MCP | Basic Auth, hop credentials | [Gateways and Auth](./05_agent_gateway_mcp_gateway_and_auth.md) |
-| Need to decide framework vs agent ownership | core/agent boundary | [Architecture and Concepts](./01_architecture_and_concepts.md) |
-| Agent-specific guardrail breaks another agent | extension model, domain imports | [Guardrails and Judges](./06_guardrails_judges_and_transaction_evaluation.md) |
-| Judge does not run for a transaction | sampling, transaction signals | [Guardrails and Judges](./06_guardrails_judges_and_transaction_evaluation.md) |
-| Groundedness gets the wrong context | RAG context, MCP evidence, judge inputs | [RAG/Grounding](./07_rag_business_context_and_grounding.md) |
-| RAG returns no useful content | provider, ingestion, embeddings | [RAG/Grounding](./07_rag_business_context_and_grounding.md) |
-| Unsure whether to use RAG, memory or a tool | responsibility separation | [Architecture and Concepts](./01_architecture_and_concepts.md) |
-| Memory disappears across sessions | LTM vs conversation memory | [LTM and Checkpoint](./08_long_term_memory_and_checkpoint.md) |
-| Memory leaks across customer/agent | identity isolation | [LTM and Checkpoint](./08_long_term_memory_and_checkpoint.md) |
-| Need `reasoning_content` | `ainvoke_response()` | [LLM Rich Response](./09_llm_rich_response_reasoning.md) |
-| `reasoning_content` is `None` | provider/model does not expose it | [LLM Rich Response](./09_llm_rich_response_reasoning.md) |
-| Too many LLM calls | deterministic routing, concurrency, cache | [Performance](./10_performance_cache_and_async_runtime.md) |
-| Deadlock across event loops | cross-loop runtime/sequence | [Performance](./10_performance_cache_and_async_runtime.md) |
-| Logs/traces do not correlate the same agent | labels, IDs, observability mapping | [Observability](./11_observability_persistence_and_operational_readiness.md) |
-| Historical example no longer compiles | stale docs vs current API | [README Alignment Validation](./VALIDATION_README_ALIGNMENT.md) |
-| Need to create a new agent from scratch | complete flow | [`README_en.md`](../../../README_en.md) |
+| The framework does not find the correct agent/intent | routing, intents, threshold, deterministic/LLM mode | [Routing and Stickiness](docs/developer/en/02_routing_stickiness_and_intent_shift.md) |
+| The agent gets stuck on the same subject and does not change intent | route stickiness, intent shift, handoff | [Routing and Stickiness](docs/developer/en/02_routing_stickiness_and_intent_shift.md) |
+| An answer that should fill a parameter is interpreted as a new intent | transactional precedence, parameter extraction | [Transactional Workflows](docs/developer/en/03_transaction_workflows_and_state.md) |
+| The transaction keeps asking for the same parameter | transaction state, extractor, schema | [Transactional Workflows](docs/developer/en/03_transaction_workflows_and_state.md) and [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
+| “yes/no” confirmation does not continue the flow | confirmation state, transaction state | [Transactional Workflows](docs/developer/en/03_transaction_workflows_and_state.md) |
+| A completed transaction reappears | old checkpoint versus active transaction state | [Transactional Workflows](docs/developer/en/03_transaction_workflows_and_state.md) and [LTM/Checkpoint](docs/developer/en/08_long_term_memory_and_checkpoint.md) |
+| The system says it executed something, but there is no evidence | MCP result, `COMPLETED` state, transactional judges | [Transactional Workflows](docs/developer/en/03_transaction_workflows_and_state.md) and [Guardrails/Judges](docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md) |
+| A tool does not appear or cannot be found | `tools.yaml`, MCP catalog, discovery | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
+| MCP Server does not appear in the catalog | registration, manifest/discovery, MCP Gateway | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) and [Gateways](docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md) |
+| Parameters sent to the tool are wrong | schema, mapping, BusinessContext, extractor | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
+| A transactional operation executes without confirmation | tool policy, `require_confirmation` | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
+| A name search requires an overly exact match | parameter extraction/mapping and agent logic | [MCP/Tools](docs/developer/en/04_mcp_integration_tools_and_policies.md) |
+| I receive 401 between gateway/backend/MCP | Basic Auth, credentials per hop | [Gateways and Auth](docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md) |
+| I need to decide whether something belongs to the framework or the agent | core/agent boundary | [Architecture and Concepts](docs/developer/en/01_architecture_and_concepts.md) |
+| An agent-specific guardrail is breaking another agent | extensibility, domain imports in the core | [Guardrails and Judges](docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md) |
+| A judge does not run in a transaction | sampling, `always_run_for_transactional`, transaction signals | [Guardrails and Judges](docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md) |
+| Groundedness is evaluating without the correct context | RAG context, MCP evidence, judge inputs | [RAG/Grounding](docs/developer/en/07_rag_business_context_and_grounding.md) |
+| RAG does not find content | provider, ingestion, embeddings, configuration | [RAG/Grounding](docs/developer/en/07_rag_business_context_and_grounding.md) |
+| I do not know whether to use RAG, memory, or a tool | separation of responsibilities | [Architecture and Concepts](docs/developer/en/01_architecture_and_concepts.md) and [RAG/Grounding](docs/developer/en/07_rag_business_context_and_grounding.md) |
+| Memory disappears when changing sessions | LTM versus conversation memory | [LTM and Checkpoint](docs/developer/en/08_long_term_memory_and_checkpoint.md) |
+| Memory from one customer/agent appears in another | identity key, tenant/agent/customer isolation | [LTM and Checkpoint](docs/developer/en/08_long_term_memory_and_checkpoint.md) |
+| I need to retrieve `reasoning_content` | `ainvoke_response()` | [LLM Rich Response](docs/developer/en/09_llm_rich_response_reasoning.md) |
+| `reasoning_content` is `None` | provider/model does not expose the field | [LLM Rich Response](docs/developer/en/09_llm_rich_response_reasoning.md) |
+| There are unnecessary LLM calls | deterministic routing, concurrency, cache | [Performance](docs/developer/en/10_performance_cache_and_async_runtime.md) |
+| There is a deadlock or wait across event loops | cross-loop sequence/runtime | [Performance](docs/developer/en/10_performance_cache_and_async_runtime.md) |
+| Logs/traces do not correlate the same agent | labels, IDs, and observability mapping | [Observability](docs/developer/en/11_observability_persistence_and_operational_readiness.md) |
+| Sequence is interfering with processing | asynchronous sequence implementation | [Observability](docs/developer/en/11_observability_persistence_and_operational_readiness.md) and [Performance](docs/developer/en/10_performance_cache_and_async_runtime.md) |
+| An old example does not compile | historical documentation versus current API | [README vs Code Validation](docs/developer/en/VALIDATION_README_ALIGNMENT.md) |
+| I need to create a new agent from scratch | complete flow | [`README_en.md`](README_en.md) |
+| I need to know where to place a new feature | architecture and boundaries | [Architecture and Concepts](docs/developer/en/01_architecture_and_concepts.md) |
 
 ### Search by feature
 
-### [01 — Architecture and Concepts](./01_architecture_and_concepts.md)
+### [01 — Architecture and Concepts](docs/developer/en/01_architecture_and_concepts.md)
 
-**What it is:** component, contract and responsibility-boundary reference.
+**What it is:** overview of components, contracts, and responsibility boundaries.
 
-**Use it when:** understanding the platform or deciding where a feature belongs.
+**Use when:** you need to understand the platform, decide where to implement something, or avoid coupling between core and agent.
 
-### [02 — Routing, Route Stickiness and Intent Shift](./02_routing_stickiness_and_intent_shift.md)
+### [02 — Routing, Route Stickiness, and Intent Shift](docs/developer/en/02_routing_stickiness_and_intent_shift.md)
 
-**What it is:** agent/intent discovery, stickiness, handoff and intent-shift reference.
+**What it is:** complete reference for agent/intent discovery, stickiness, handoff, and intent changes.
 
-**Use it when:** routing is wrong or session continuity behaves incorrectly.
+**Use when:** the message goes to the wrong agent, does not change intent, or loses continuity.
 
-### [03 — Transactional Workflows and State](./03_transaction_workflows_and_state.md)
+### [03 — Transactional Workflows and State](docs/developer/en/03_transaction_workflows_and_state.md)
 
-**What it is:** multi-turn transaction lifecycle, states, confirmation, resume and execution evidence.
+**What it is:** multi-turn transaction lifecycle, states, confirmation, pause/resume, and operational evidence.
 
-**Use it when:** transactions loop, resume incorrectly or perform critical operations.
+**Use when:** there are loops, incorrect confirmations, incorrect resumes, or critical operations.
 
-### [04 — MCP, Tools, Policies and Parameter Extraction](./04_mcp_integration_tools_and_policies.md)
+### [04 — MCP, Tools, Policies, and Parameter Extraction](docs/developer/en/04_mcp_integration_tools_and_policies.md)
 
-**What it is:** tools, MCP Servers, mappings, policies and extraction reference.
+**What it is:** reference for tools, MCP Servers, mappings, policies, and parameter extraction.
 
-**Use it when:** building or troubleshooting tool integration.
+**Use when:** tool integration/execution is incorrect or needs to be created.
 
-### [05 — Agent Gateway, MCP Gateway and Authentication](./05_agent_gateway_mcp_gateway_and_auth.md)
+### [05 — Agent Gateway, MCP Gateway, and Authentication](docs/developer/en/05_agent_gateway_mcp_gateway_and_auth.md)
 
-**What it is:** gateway responsibilities, governance and component authentication.
+**What it is:** gateway responsibilities, governance, and authentication between components.
 
-**Use it when:** troubleshooting ingress, catalog, authorization or gateway deployment.
+**Use when:** there is an ingress, catalog, authorization, 401, or gateway deployment problem.
 
-### [06 — Guardrails, Judges and Transaction Evaluation](./06_guardrails_judges_and_transaction_evaluation.md)
+### [06 — Guardrails, Judges, and Transaction Evaluation](docs/developer/en/06_guardrails_judges_and_transaction_evaluation.md)
 
-**What it is:** native/external validation, judges, grounding and transaction evaluation.
+**What it is:** native/external validations, judges, grounding, and rules for transactional turns.
 
-**Use it when:** validation blocks, skips or evaluates incorrectly.
+**Use when:** a validation blocks, does not run, or produces an incorrect evaluation.
 
-### [07 — RAG, BusinessContext and Grounding](./07_rag_business_context_and_grounding.md)
+### [07 — RAG, BusinessContext, and Grounding](docs/developer/en/07_rag_business_context_and_grounding.md)
 
-**What it is:** RAG providers, retrieved context, BusinessContext and grounding.
+**What it is:** RAG providers, retrieved context, BusinessContext, and grounding.
 
-**Use it when:** retrieved knowledge does not reach the runtime/judge correctly.
+**Use when:** retrieved knowledge does not correctly reach the agent/judge.
 
-### [08 — Long-Term Memory and Checkpoint](./08_long_term_memory_and_checkpoint.md)
+### [08 — Long-Term Memory and Checkpoint](docs/developer/en/08_long_term_memory_and_checkpoint.md)
 
-**What it is:** durable memory, conversational memory, identity and state snapshots.
+**What it is:** durable memory, conversation memory, identity, and state snapshots.
 
-**Use it when:** context disappears, leaks or resumes incorrectly.
+**Use when:** context disappears, leaks, or the workflow resumes from the wrong place.
 
-### [09 — LLM Rich Response and reasoning_content](./09_llm_rich_response_reasoning.md)
+### [09 — LLM Rich Response and reasoning_content](docs/developer/en/09_llm_rich_response_reasoning.md)
 
-**What it is:** structured inference output beyond the `str` returned by `ainvoke()`.
+**What it is:** structured inference response beyond the `str` returned by `ainvoke()`.
 
-**Use it when:** consumers require provider metadata, usage or reasoning exposed by the provider.
+**Use when:** consumers need metadata, usage, or reasoning exposed by the provider.
 
-### [10 — Performance, Cache and Async Runtime](./10_performance_cache_and_async_runtime.md)
+### [10 — Performance, Cache, and Async Runtime](docs/developer/en/10_performance_cache_and_async_runtime.md)
 
-**What it is:** concurrency, caching, LLM and event-loop optimization reference.
+**What it is:** concurrency, cache, LLM, and event-loop optimizations.
 
-**Use it when:** reducing avoidable latency or diagnosing deadlocks.
+**Use when:** there is avoidable latency, serial processing, or deadlock.
 
-### [11 — Observability, Persistence and Operational Readiness](./11_observability_persistence_and_operational_readiness.md)
+### [11 — Observability, Persistence, and Operational Readiness](docs/developer/en/11_observability_persistence_and_operational_readiness.md)
 
-**What it is:** correlation, events, labels, sequencing, persistence and production diagnostics.
+**What it is:** correlation, events, labels, sequence, persistence, and diagnostics.
 
-**Use it when:** proving execution paths or diagnosing production behavior.
+**Use when:** it is necessary to prove the executed path or diagnose production.
 
 ### Main tutorial
 
-[`README_en.md`](../../../README_en.md) remains the complete step-by-step guide.
+[`README_en.md`](README_en.md) remains the reference for the complete step-by-step flow:
+
+`architecture → configuration → agent creation → registration → state → routing → tools → MCP → identity → execution → tests → gateways → memory → RAG`.
 
 ### Maintenance
 
-Do not create another tutorial parallel to the root README.
+Do not create another tutorial in parallel with `README_en.md`.
 
-When a feature evolves:
+When evolving a feature:
 
-- update the README only when the normal developer flow changes;
-- update the specialized manual with behavior, configuration, examples and troubleshooting;
-- update SPECs when contracts change;
+- update the README only if the normal development flow changed;
+- update the specialized manual with behavior, configuration, examples, and troubleshooting;
+- update SPECs if the contract changed;
 - keep release notes as history, not as the only current documentation.
diff --git a/docs/developer/en/VALIDATION_README_ALIGNMENT.md b/docs/developer/en/VALIDATION_README_ALIGNMENT.md
index a34a359..9d2c2ee 100644
--- a/docs/developer/en/VALIDATION_README_ALIGNMENT.md
+++ b/docs/developer/en/VALIDATION_README_ALIGNMENT.md
@@ -1,27 +1,39 @@
-
 ### Documentation Alignment Validation
 
-### Purpose
+### Goal
 
-Record how this version's documentation was reorganized and which sources developers should trust.
+Record how the documentation for this version was reorganized and which sources developers should use.
 
 ### Structural decision
 
-The root `README_en.md` / `README.md` is the **single end-to-end main tutorial**.
+The root `README_en.md` is the **single end-to-end main tutorial**.
 
-The former `01_architecture_and_agent_development.md` was removed because it repeated much of the README but not all of it. That created ambiguity: two documents appeared to teach the same workflow while one was partial.
+The former `01_architecture_and_agent_development.md` was removed because it repeated a large part of the README, but not all of it. This created ambiguity: two documents appeared to teach the same thing, but one was partial.
 
-The new structure replaces it with `01_architecture_and_concepts.md`, containing only architecture, concepts, responsibilities and extension criteria.
+The new structure replaces that file with `01_architecture_and_concepts.md`, which contains only architecture, concepts, responsibilities, and extension criteria.
 
-### `README_old2.md` validation
+### Validation of `README_old2.md`
 
-`Documentacao/README_old2.md` remains useful as historical material but is not the primary development source.
+`Documentacao/README_old2.md` remains useful as history, but it is not the primary source for development.
 
-Later evolution found in the current README/code includes SPECs/SDDs, richer `llm_profiles.yaml` guidance, Channel Gateway, canonical contracts, current memory composition, `RuntimeContext`, tool helpers, transaction helpers, direct MCP responses and gateway/RAG/memory/policy evolution.
+Later evolutions were found in the current README and code, including:
 
-### Main README correction
+- SPECs/SDDs;
+- more complete `llm_profiles.yaml` configuration;
+- Channel Gateway and canonical contracts;
+- `memory` and `summary_memory` in the current agent lifecycle;
+- `prepare_memory_context()` and `build_messages()`;
+- `RuntimeContext`;
+- `normalize_tools_by_intent()`;
+- `build_tool_arguments()`;
+- `execute_tools_for_intent()`;
+- transaction-state helpers;
+- direct MCP responses;
+- evolution of gateways, RAG, memory, and policies.
 
-The generated package corrects this typo:
+### Correction applied to the main README
+
+The following typo was corrected in the generated package:
 
 ```python
 from app.agents.financeiro_agent import FinanceirotAgent
@@ -33,7 +45,7 @@ to:
 from app.agents.financeiro_agent import FinanceiroAgent
 ```
 
-The correct class is confirmed by code and the rest of the documentation.
+The correct class is confirmed by the code and the rest of the documentation.
 
 ### APIs confirmed in the current implementation
 
@@ -52,7 +64,7 @@ AgentRuntimeMixin.build_direct_mcp_answer()
 
 ### Trust order
 
-1. version code;
+1. code for the version;
 2. main README for the same version;
 3. SPECs/SDDs;
 4. specialized manuals;
@@ -63,9 +75,9 @@ AgentRuntimeMixin.build_direct_mcp_answer()
 
 A feature evolution should update:
 
-1. the main README **only when the normal development path changes**;
-2. the feature's specialized manual with technical detail, behavior, configuration and troubleshooting;
-3. the SPEC when a contract changes;
-4. a release note when historical recording is needed.
+1. the main README, **only if it changes the normal development path**;
+2. the feature's specialized manual, with technical details, behavior, configuration, and troubleshooting;
+3. the SPEC, when there is a contract change;
+4. the release note, when it is necessary to record the historical change.
 
-Do not create another “main manual” for a feature. Do not keep functional corrections permanently only in release notes.
+Do not create a new “main manual” for a feature. Do not keep functional fixes permanently only in release notes.
diff --git a/docs/developer/pt/02_routing_stickiness_and_intent_shift.md b/docs/developer/pt/02_routing_stickiness_and_intent_shift.md
index 891a197..a368d7b 100644
--- a/docs/developer/pt/02_routing_stickiness_and_intent_shift.md
+++ b/docs/developer/pt/02_routing_stickiness_and_intent_shift.md
@@ -728,6 +728,7 @@ GET /debug/env
 
 ### Arquitetura — Global Supervisor
 
+```text
 Usuário / Frontend
         │
         ▼
@@ -745,6 +746,8 @@ Usuário / Frontend
       ▼         ▼         ▼            ▼
 Backend      Backend   Backend     Backend
 Contas       Ofertas   Suporte     Cobrança
+```
+
 Cada backend continua sendo um projeto independente, com seus próprios agentes, prompts, MCPs e deploy, mas todos usam a mesma biblioteca agent_framework.
 
 ### Estado global
@@ -780,18 +783,21 @@ A capacidade usa um perfil LLM leve para decidir o tratamento global do turno se
 
 ### Fluxo
 
+```text
 Mensagem -> Classificador LLM leve
   CONTINUE + agente ativo -> agente atual
   ROUTE / baixa confiança / erro -> Enterprise Router
   HUMAN_HANDOFF -> nó human_handoff
   END_SESSION -> nó end_session
 As ações globais podem ser reconhecidas no primeiro turno. Isso permite que “quero falar com uma pessoa” ou “pode encerrar” não dependam de um agente de domínio já selecionado.
+```
 
 ### Configuração
 
 
 ### .env
 
+```text
 ENABLE_ROUTE_STICKINESS=true
 ROUTE_STICKINESS_LLM_PROFILE=route_continuity
 ROUTE_STICKINESS_CONFIDENCE_THRESHOLD=0.90
@@ -799,6 +805,7 @@ ROUTE_STICKINESS_HISTORY_TURNS=2
 ROUTE_STICKINESS_MAX_TOKENS=80
 HUMAN_HANDOFF_MESSAGE=Vou encaminhar seu atendimento para uma pessoa.
 END_SESSION_MESSAGE=Atendimento encerrado. Obrigado pelo contato.
+```
 
 ### llm_profiles.yaml