docs(mcp): add architecture and flow diagrams

Author: juanklagos

docs/en/41-complete-mcp-reference.md

@@ -28,6 +28,28 @@ It gives AI clients a structured way to:
 
 It is not just documentation access. It is the runnable interface to the framework.
 
+## Visual architecture
+
+```mermaid
+flowchart LR
+  A["User"] --> B["AI Client"]
+  B --> C["sdd-mcp"]
+  C --> D["sdd-core"]
+  C --> E["MCP Resources"]
+  D --> F["Target Project"]
+  E --> F
+  F --> G["idea/"]
+  F --> H["specs/"]
+  F --> I["bitacora/"]
+  F --> J["docs/"]
+```
+
+Reading path:
+- the AI client reads MCP resources and prompts
+- `sdd-mcp` exposes the operational contract
+- `sdd-core` performs the actual project mutations
+- the target project stores the resulting SDD artifacts
+
 ## What the user can expect
 
 When an AI client is connected to `sdd-mcp`, the user can expect:
@@ -429,6 +451,18 @@ These resource templates are for managed projects under `./www/<project-name>/`.
 
 ## Recommended user flow
 
+```mermaid
+flowchart LR
+  A["Connect MCP"] --> B["Read policy + quickstart"]
+  B --> C["Create SDD base"]
+  C --> D["Create first spec"]
+  D --> E["Validate"]
+  E --> F["Check gate"]
+  F --> G["Record consent"]
+  G --> H["Implement"]
+  H --> I["Write logs and handoff"]
+```
+
 1. Connect the MCP server.
 2. Read `sdd-policy` and `sdd-quickstart`.
 3. Create the SDD base with `sdd_create_workspace` or external bootstrap scripts.

docs/es/41-referencia-completa-mcp.md

@@ -28,6 +28,28 @@ Da a los clientes IA una forma estructurada de:
 
 No es solo acceso a documentación. Es la interfaz ejecutable del framework.
 
+## Arquitectura visual
+
+```mermaid
+flowchart LR
+  A["Usuario"] --> B["Cliente IA"]
+  B --> C["sdd-mcp"]
+  C --> D["sdd-core"]
+  C --> E["Resources MCP"]
+  D --> F["Proyecto destino"]
+  E --> F
+  F --> G["idea/"]
+  F --> H["specs/"]
+  F --> I["bitacora/"]
+  F --> J["docs/"]
+```
+
+Ruta de lectura:
+- el cliente IA lee resources y prompts MCP
+- `sdd-mcp` expone el contrato operativo
+- `sdd-core` ejecuta las mutaciones reales del proyecto
+- el proyecto destino guarda los artefactos SDD resultantes
+
 ## Qué puede esperar el usuario
 
 Cuando un cliente IA está conectado a `sdd-mcp`, el usuario puede esperar:
@@ -429,6 +451,18 @@ Estos resource templates son para proyectos administrados bajo `./www/<nombre-pr
 
 ## Flujo recomendado para el usuario
 
+```mermaid
+flowchart LR
+  A["Conectar MCP"] --> B["Leer policy + quickstart"]
+  B --> C["Crear base SDD"]
+  C --> D["Crear primera spec"]
+  D --> E["Validar"]
+  E --> F["Revisar compuerta"]
+  F --> G["Registrar consentimiento"]
+  G --> H["Implementar"]
+  H --> I["Escribir logs y handoff"]
+```
+
 1. Conecta el servidor MCP.
 2. Lee `sdd-policy` y `sdd-quickstart`.
 3. Crea la base SDD con `sdd_create_workspace` o con scripts de bootstrap externo.