diff --git a/.harness/playbooks/sdlc-deep-audit.mjs b/.harness/playbooks/sdlc-deep-audit.mjs
index 0eb69d9f1..627f50c7e 100644
--- a/.harness/playbooks/sdlc-deep-audit.mjs
+++ b/.harness/playbooks/sdlc-deep-audit.mjs
@@ -191,27 +191,27 @@ function auditEvaluationEngine() {
}
// Check for SatelliteEvaluationPipeline (GT-281)
- const pipelineFile = "packages/core-domain/src/application/services/satellite-evaluation-pipeline.service.ts";
+ const pipelineFile = "src/packages/core-domain/src/application/services/satellite-evaluation-pipeline.service.ts";
const hasPipeline = exists(pipelineFile);
// Check for SatelliteManifest type
- const manifestTypeFile = "packages/core-domain/src/domain/satellite-manifest.ts";
+ const manifestTypeFile = "src/packages/core-domain/src/domain/satellite-manifest.ts";
const hasManifestType = exists(manifestTypeFile);
// Check for end-to-end pipeline test
- const pipelineTest = "packages/core-domain/src/application/services/satellite-evaluation-pipeline.spec.ts";
+ const pipelineTest = "src/packages/core-domain/src/application/services/satellite-evaluation-pipeline.spec.ts";
const hasPipelineTest = exists(pipelineTest);
// Check for CLI --manifest/--phase options in validate command
- const cliCommand = "sdk/cli/src/commands/validate/validate.command.ts";
+ const cliCommand = "src/sdk/cli/src/commands/validate/validate.command.ts";
const cliHasManifest = exists(cliCommand) ? (read(cliCommand) || "").includes("--manifest") : false;
// Check that ValidateSatelliteUseCase accepts manifest input
- const useCaseFile = "packages/core-domain/src/application/use-cases/validate-satellite.use-case.ts";
+ const useCaseFile = "src/packages/core-domain/src/application/use-cases/validate-satellite.use-case.ts";
const useCaseAcceptsManifest = exists(useCaseFile) ? (read(useCaseFile) || "").includes("manifest?:") : false;
// Check the 3 interfaces converge on same UseCase
- const mcpToolFile = "packages/mcp-server/src/tools/validate.tool.ts";
+ const mcpToolFile = "src/packages/mcp-server/src/tools/validate.tool.ts";
const mcpCallsPipeline = exists(mcpToolFile) ? (read(mcpToolFile) || "").includes("runPipeline") : false;
return {
@@ -267,30 +267,30 @@ function auditClientIngestion() {
// ── 5. LAS TRES INTERFACES ───────────────────────────────────────────
function auditThreeInterfaces() {
- const cliCommands = exists("sdk/cli/src/commands") ? fs.readdirSync(path.join(root, "sdk/cli/src/commands")).filter(f => !f.startsWith(".")) : [];
- const mcpTools = exists("packages/mcp-server/src/tools") ? fs.readdirSync(path.join(root, "packages/mcp-server/src/tools")).filter(f => f.endsWith(".ts") && !f.includes("spec")) : [];
- const coreApiControllers = exists("apps/core-api/src/presentation/controllers") ? fs.readdirSync(path.join(root, "apps/core-api/src/presentation/controllers")).filter(f => f.endsWith(".ts") && !f.includes("spec")) : [];
+ const cliCommands = exists("src/sdk/cli/src/commands") ? fs.readdirSync(path.join(root, "src/sdk/cli/src/commands")).filter(f => !f.startsWith(".")) : [];
+ const mcpTools = exists("src/packages/mcp-server/src/tools") ? fs.readdirSync(path.join(root, "src/packages/mcp-server/src/tools")).filter(f => f.endsWith(".ts") && !f.includes("spec")) : [];
+ const coreApiControllers = exists("src/apps/core-api/src/presentation/controllers") ? fs.readdirSync(path.join(root, "src/apps/core-api/src/presentation/controllers")).filter(f => f.endsWith(".ts") && !f.includes("spec")) : [];
// Check if each surface exposes an EVALUATION operation
let cliHasEval = false;
let mcpHasEval = false;
let apiHasEval = false;
- const cliEvalFiles = globFiles("sdk/cli/src/commands/**/*.ts").filter(f => !f.includes("spec"));
+ const cliEvalFiles = globFiles("src/sdk/cli/src/commands/**/*.ts").filter(f => !f.includes("spec"));
for (const f of cliEvalFiles) {
const c = read(f);
if (!c) continue;
if (c.includes("evaluate") || c.includes("validate") || c.includes("gate")) { cliHasEval = true; break; }
}
- const mcpEvalFiles = globFiles("packages/mcp-server/src/tools/**/*.ts");
+ const mcpEvalFiles = globFiles("src/packages/mcp-server/src/tools/**/*.ts");
for (const f of mcpEvalFiles) {
const c = read(f);
if (!c) continue;
if (c.includes("evaluate") || c.includes("validate") || c.includes("gate")) { mcpHasEval = true; break; }
}
- const apiEvalFiles = globFiles("apps/core-api/src/**/*.ts");
+ const apiEvalFiles = globFiles("src/apps/core-api/src/**/*.ts");
for (const f of apiEvalFiles) {
const c = read(f);
if (!c) continue;
@@ -298,12 +298,12 @@ function auditThreeInterfaces() {
}
// Check if all three route to same underlying service
- const coreDomainFiles = globFiles("packages/core-domain/src/**/*.ts").filter(f => !f.includes("spec"));
+ const coreDomainFiles = globFiles("src/packages/core-domain/src/**/*.ts").filter(f => !f.includes("spec"));
let sharedUseCase = null;
for (const f of coreDomainFiles) {
const c = read(f);
if (!c) continue;
- if (c.includes("ValidateSatelliteUseCase")) {
+ if (c.includes("class ValidateSatelliteUseCase")) {
const name = f.split("/").pop().replace(".ts", "");
sharedUseCase = name;
break;
@@ -329,7 +329,7 @@ function auditThreeInterfaces() {
function auditActionableReports() {
// GT-282: check for structured evaluation types with actionable detail fields
- const manifestType = "packages/core-domain/src/domain/satellite-manifest.ts";
+ const manifestType = "src/packages/core-domain/src/domain/satellite-manifest.ts";
const manifestContent = read(manifestType);
const hasRemediation = manifestContent?.includes("remediation");
@@ -337,23 +337,23 @@ function auditActionableReports() {
const hasGateRef = manifestContent?.includes("gateRef");
// Check for ADR-0073 output envelope in evaluation verdict
- const pipelineService = "packages/core-domain/src/application/services/satellite-evaluation-pipeline.service.ts";
+ const pipelineService = "src/packages/core-domain/src/application/services/satellite-evaluation-pipeline.service.ts";
const pipelineContent = read(pipelineService);
const hasOutputEnvelope = pipelineContent?.includes("outputEnvelope") && pipelineContent?.includes("createSuccessEnvelope");
const hasADREnvelope = read(pipelineService)?.includes("ADR-0073") || read(manifestType)?.includes("ADR-0073");
// Check MCP includes actionable fields
- const mcpTool = "packages/mcp-server/src/tools/validate.tool.ts";
+ const mcpTool = "src/packages/mcp-server/src/tools/validate.tool.ts";
const mcpContent = read(mcpTool);
const mcpShowsRemediation = mcpContent?.includes("remediation");
// Check CLI shows actionable details
- const cliCommand = "sdk/cli/src/commands/validate/validate.command.ts";
+ const cliCommand = "src/sdk/cli/src/commands/validate/validate.command.ts";
const cliContent = read(cliCommand);
const cliShowsRemediation = cliContent?.includes("remediation") || cliContent?.includes("Remedio");
// Check tests verify actionable fields
- const pipelineTest = "packages/core-domain/src/application/services/satellite-evaluation-pipeline.spec.ts";
+ const pipelineTest = "src/packages/core-domain/src/application/services/satellite-evaluation-pipeline.spec.ts";
const testContent = read(pipelineTest);
const testChecksRemediation = testContent?.includes("remediation");
const testChecksOutputEnvelope = testContent?.includes("outputEnvelope");
@@ -423,8 +423,8 @@ function auditGovernance() {
// GT-412: runtime policy enforcement must be mandatory before governed
// capabilities execute, and hosted defaults must use the real OPA adapter.
- const runtimeService = read("packages/agent-runtime/src/application/agent-runtime.service.ts") || "";
- const runtimeFactory = read("apps/agent-runtime-api/src/agent-runtime/runtime.factory.ts") || "";
+ const runtimeService = read("src/packages/agent-runtime/src/application/agent-runtime.service.ts") || "";
+ const runtimeFactory = read("src/apps/agent-runtime-api/src/agent-runtime/runtime.factory.ts") || "";
const preflightIdx = runtimeService.indexOf("steps.push('policy-preflight')");
const harnessIdx = runtimeService.indexOf("steps.push('harness-execute')");
const approvalIdx = runtimeService.indexOf("steps.push('approval')");
@@ -454,7 +454,7 @@ function auditGovernance() {
// ── 8. VERIFICACIONES PUNTUALES ──────────────────────────────────────
function auditPointChecks() {
- const scaffoldCmdExists = exists("sdk/cli/src/commands/architecture/scaffold.command.ts");
+ const scaffoldCmdExists = exists("src/sdk/cli/src/commands/architecture/scaffold.command.ts");
// Check for broken ADR references
let brokenAdrRefs = 0;
@@ -472,7 +472,7 @@ function auditPointChecks() {
// Check for invented commands in docs
let inventedCommands = 0;
const realCommands = new Set(
- walk("sdk/cli/src/commands").filter(f => f.endsWith(".ts") && !f.includes("spec"))
+ walk("src/sdk/cli/src/commands").filter(f => f.endsWith(".ts") && !f.includes("spec"))
.map(f => f.split("/").pop().replace(".command.ts", "").replace(".ts", ""))
);
for (const f of allFiles) {
@@ -500,14 +500,14 @@ function auditPointChecks() {
// ── 9. INTEGRACIÓN AGENT RUNTIME ─────────────────────────────────────
function auditAgentRuntimeConnectivity() {
- const hasAgentRuntimeApi = exists("apps/agent-runtime-api");
+ const hasAgentRuntimeApi = exists("src/apps/agent-runtime-api");
- const sdkAgentClient = exists("packages/sdk-client/src/rest/agent.client.ts");
+ const sdkAgentClient = exists("src/packages/sdk-client/src/rest/agent.client.ts");
- const cliAgentCmd = "sdk/cli/src/commands/agents/agents.command.ts";
+ const cliAgentCmd = "src/sdk/cli/src/commands/agents/agents.command.ts";
const cliHasAgentRun = exists(cliAgentCmd) ? (read(cliAgentCmd) || "").includes("runAgent") : false;
- const mcpAgentTool = "packages/mcp-server/src/tools/agent.tools.ts";
+ const mcpAgentTool = "src/packages/mcp-server/src/tools/agent.tools.ts";
const mcpHasAgentRun = exists(mcpAgentTool) ? (read(mcpAgentTool) || "").includes("evolith-agent-run") : false;
const connected = hasAgentRuntimeApi && sdkAgentClient && cliHasAgentRun && mcpHasAgentRun;
diff --git a/.harness/scripts/ci/03-validate-root-cleanliness.mjs b/.harness/scripts/ci/03-validate-root-cleanliness.mjs
index 9af0094a5..255e28fac 100755
--- a/.harness/scripts/ci/03-validate-root-cleanliness.mjs
+++ b/.harness/scripts/ci/03-validate-root-cleanliness.mjs
@@ -89,6 +89,7 @@ const allowedDirectories = new Set([
// sdk/, tests/) was relocated here, so those are no longer permitted at root.
"src",
// Product documentation corpus.
+ "docs",
"product",
"examples",
"wiki"
diff --git a/README.es.md b/README.es.md
index f556fc350..3d129f0a2 100644
--- a/README.es.md
+++ b/README.es.md
@@ -8,6 +8,8 @@
[]()
[](https://github.com/beyondnetcode/evolith_arch32/actions)
+> **[Comenzar Aquí: Guía de Instalación Paso a Paso](./docs/guides/evolith-quickstart.es.md)**
+
@@ -147,6 +149,7 @@ Evolith se distribuye como una suite de productos coordinados sobre una base com
| **[MCP Services](product/products/mcp-services/README.es.md)** | Gobernanza como contexto en vivo para LLMs y agentes de IA (47 tools, 9 resources, 8 prompts) |
| **[Agent Runtime](reference/core/architecture/foundations/README.es.md)** | Capa de mediación agéntica — orquesta el Core mediante Puertos y Adaptadores; Hermes es uno de los adaptadores reemplazables |
| **[Evolith Tracker](product/products/evolith-tracker/README.es.md)** | Gobernanza del ciclo de vida del negocio — fases, propietarios, financiación y ROI |
+| **[Narrativa Comercial](product/suite/vision/evolith-commercial-brochure.es.md)** | Estrategia de producto y monetización empresarial (Despliegue Hub & Spoke) |
| **[Rulesets](src/rulesets/README.es.md)** | Reglas de aplicación legibles por máquina por topología |
| **[Políticas OPA](src/rulesets/opa/README.es.md)** | Controles de política granulares integrados en el pipeline |
| **[Schemas y Manifests](src/rulesets/schema/README.es.md)** | Contratos estructurados para artefactos y definiciones de topología |
diff --git a/README.md b/README.md
index 94e26b661..bf11b6328 100644
--- a/README.md
+++ b/README.md
@@ -9,6 +9,8 @@
[]()
[](https://github.com/beyondnetcode/evolith_arch32/actions)
+> **[Start Here: Step-by-Step Quickstart Guide](./docs/guides/evolith-quickstart.md)**
+
@@ -148,6 +150,7 @@ Evolith ships as a suite of coordinated products built on a common foundation.
| **[MCP Services](product/products/mcp-services/README.md)** | Governance as live context for LLMs and AI agents (47 tools, 9 resources, 8 prompts) |
| **[Agent Runtime](reference/core/architecture/foundations/README.md)** | Agentic mediation layer — orchestrates Core through Ports & Adapters; Hermes is one replaceable adapter |
| **[Evolith Tracker](product/products/evolith-tracker/README.md)** | Business lifecycle governance — phases, owners, funding, and ROI |
+| **[Commercial Vision](product/suite/vision/evolith-commercial-brochure.md)** | Product strategy and enterprise monetization narrative (Hub & Spoke deployment) |
| **[Rulesets](src/rulesets/README.md)** | Machine-readable enforcement rules per topology |
| **[OPA Policies](src/rulesets/opa/README.md)** | Fine-grained policy checks integrated into the pipeline |
| **[Schemas & Manifests](src/rulesets/schema/README.md)** | Structured contracts for artifacts and topology definitions |
diff --git a/docs/guides/evolith-quickstart.es.md b/docs/guides/evolith-quickstart.es.md
new file mode 100644
index 000000000..2492babe6
--- /dev/null
+++ b/docs/guides/evolith-quickstart.es.md
@@ -0,0 +1,68 @@
+# Guía de Inicio Rápido: Evolith (Paso a Paso)
+
+Esta guía te ayudará a instalar y poner en marcha Evolith en **menos de 5 minutos**, para que puedas comenzar a validar la arquitectura de tu código.
+
+---
+
+## Paso 1: Levantar el Cerebro (Evolith Core API)
+
+El Core API es el servidor central que contiene las reglas de arquitectura de tu empresa. Debes levantarlo primero para que los clientes puedan consultarlo.
+
+Tienes dos opciones para iniciarlo en tu máquina local:
+
+### Opción A: Vía Docker Compose (Más Rápido)
+Ideal para desarrolladores. Levanta la API y la base de datos PostgreSQL mínima necesaria.
+```bash
+docker-compose -f product/infra/docker-compose.yml up -d postgres
+```
+
+### Opción B: Vía Kubernetes / Helm (Entorno Completo)
+Ideal para simulaciones de producción o arquitectos. Levanta el clúster local, la base de datos, el Gateway y el Core API.
+```bash
+./.harness/scripts/run-core-local.sh
+```
+
+Una vez que termine, el servidor estará escuchando en `http://localhost:30080`. Puedes ver la documentación de la API generada en `http://localhost:30080/api/docs`.
+
+---
+
+## Paso 2: Instalar el Cliente (Evolith CLI)
+
+El CLI es la herramienta que utilizarán los desarrolladores en su día a día.
+
+1. Instala el paquete de forma global usando npm:
+```bash
+npm install -g @beyondnet/evolith-cli
+```
+
+2. Configura la URL del servidor al que el CLI debe apuntar (el que levantamos en el Paso 1). Puedes hacerlo exportando una variable de entorno:
+```bash
+export EVOLITH_CORE_URL="http://localhost:30080/api/v1"
+```
+
+---
+
+## Paso 3: Tu Primera Validación
+
+Ve a la carpeta raíz de cualquier proyecto de software (satélite) que quieras validar y ejecuta el comando de validación.
+
+```bash
+cd mi-proyecto-backend
+evolith validate
+```
+
+**¿Qué sucede detrás de escena?**
+El CLI tomará el estado actual de tu código, se conectará al Core API central y evaluará tu proyecto contra las reglas OPA y los ADRs oficiales de la empresa. En segundos, te devolverá un reporte indicando si cumples con el estándar o si hay violaciones de arquitectura.
+
+---
+
+## Paso 4: (Opcional) Conectar a tu Agente de IA
+
+Evolith no es solo para humanos. Puedes conectar tu editor de código basado en IA (Cursor, Claude Desktop, etc.) para que "entienda" tu arquitectura.
+
+Para arrancar el servidor MCP, simplemente ejecuta:
+```bash
+evolith mcp start
+```
+
+Luego, en la configuración de Cursor o Claude Desktop, añade este servidor MCP local. A partir de ese momento, tu Agente de IA sabrá qué patrones usar, qué librerías están prohibidas y cómo debe estructurar el código antes de escribir una sola línea.
diff --git a/docs/guides/evolith-quickstart.md b/docs/guides/evolith-quickstart.md
new file mode 100644
index 000000000..6899ba04e
--- /dev/null
+++ b/docs/guides/evolith-quickstart.md
@@ -0,0 +1,68 @@
+# Quickstart Guide: Evolith (Step by Step)
+
+This guide will help you install and run Evolith in **less than 5 minutes**, so you can start validating your code's architecture right away.
+
+---
+
+## Step 1: Boot the Brain (Evolith Core API)
+
+The Core API is the central server containing your enterprise architecture rules. You must boot it up first so that clients can query it.
+
+You have two options to start it on your local machine:
+
+### Option A: Via Docker Compose (Fastest)
+Ideal for developers. This boots up the API and the minimum required PostgreSQL database.
+```bash
+docker-compose -f product/infra/docker-compose.yml up -d postgres
+```
+
+### Option B: Via Kubernetes / Helm (Full Environment)
+Ideal for production simulations or architects. This spins up the local cluster, the database, the API Gateway, and the Core API.
+```bash
+./.harness/scripts/run-core-local.sh
+```
+
+Once finished, the server will be listening on `http://localhost:30080`. You can view the generated API documentation at `http://localhost:30080/api/docs`.
+
+---
+
+## Step 2: Install the Client (Evolith CLI)
+
+The CLI is the tool developers will use in their day-to-day workflow.
+
+1. Install the package globally using npm:
+```bash
+npm install -g @beyondnet/evolith-cli
+```
+
+2. Configure the server URL the CLI should point to (the one we booted in Step 1). You can do this by exporting an environment variable:
+```bash
+export EVOLITH_CORE_URL="http://localhost:30080/api/v1"
+```
+
+---
+
+## Step 3: Your First Validation
+
+Navigate to the root folder of any software project (satellite) you want to validate and run the validation command.
+
+```bash
+cd my-backend-project
+evolith validate
+```
+
+**What happens behind the scenes?**
+The CLI will take the current state of your code, connect to the central Core API, and evaluate your project against the official OPA rules and ADRs of the company. In seconds, it will return a report indicating whether you comply with the standard or if there are any architecture violations.
+
+---
+
+## Step 4: (Optional) Connect your AI Agent
+
+Evolith isn't just for humans. You can connect your AI-powered code editor (Cursor, Claude Desktop, etc.) so it "understands" your architecture.
+
+To start the MCP server, simply run:
+```bash
+evolith mcp start
+```
+
+Then, in your Cursor or Claude Desktop settings, add this local MCP server. From that moment on, your AI Agent will know which patterns to use, which libraries are forbidden, and how it should structure the code before writing a single line.
diff --git a/product/infra/helm/evolith-core-api/values-local.yaml b/product/infra/helm/evolith-core-api/values-local.yaml
index 5ad87e47d..5e94cd5dc 100644
--- a/product/infra/helm/evolith-core-api/values-local.yaml
+++ b/product/infra/helm/evolith-core-api/values-local.yaml
@@ -49,3 +49,5 @@ podDisruptionBudget:
networkPolicy:
enabled: false
+extraEnv:
+ SWAGGER_ENABLED: "true"
diff --git a/product/suite/vision/evolith-commercial-brochure.es.md b/product/suite/vision/evolith-commercial-brochure.es.md
new file mode 100644
index 000000000..a4f1fc616
--- /dev/null
+++ b/product/suite/vision/evolith-commercial-brochure.es.md
@@ -0,0 +1,83 @@
+# Evolith: Narrativa Comercial y Estrategia de Producto
+
+> **Visión Central:** Evolith es un framework ejecutable de gobernanza arquitectónica. Democratizamos el *cómo* se estructura el software (Open Source), pero comercializamos la *observabilidad y control* empresarial (Evolith Tracker).
+
+---
+
+## 1. El Problema (El Dolor del Mercado)
+
+Las empresas invierten miles de dólares en arquitectos de software para diseñar sistemas robustos y escribir Documentos de Decisión Arquitectónica (ADRs). Sin embargo, la realidad operativa es otra:
+* **La documentación muere:** Los ADRs viven en wikis estáticas que nadie consulta durante el desarrollo.
+* **Degradación silenciosa:** Con la rotación de personal y la presión por entregar rápido (y ahora, con agentes de IA generando código a gran velocidad), la arquitectura se desvía del diseño original (Architecture Drift).
+* **Deuda Técnica incontrolable:** Cuando la gerencia se da cuenta del desorden, refactorizar el sistema es costoso y paraliza el negocio.
+
+## 2. La Solución Base: Evolith Core (Open Source)
+
+**Evolith Core** transforma las reglas de arquitectura de simples "documentos de texto" a **código ejecutable**.
+
+* **Para el Desarrollador:** Funciona como un linter arquitectónico. Con un simple `evolith validate` en su CLI, sabe en segundos si su código cumple las reglas.
+* **Para los Agentes de IA:** A través del Servidor MCP, agentes como Claude o Cursor entienden instantáneamente los estándares de la empresa antes de escribir una sola línea de código.
+* **Para el Pipeline (CI/CD):** Funciona como un guardia de seguridad automatizado, bloqueando cualquier *Pull Request* que intente introducir violaciones a la arquitectura (Phase Gates).
+
+> [!TIP]
+> **La estrategia de adopción (El Caballo de Troya):** Evolith Core es **gratuito y Open Source**. El objetivo es que los desarrolladores y líderes técnicos lo adopten masivamente porque reduce la fricción, acelera los code-reviews y mejora la calidad de su trabajo diario.
+
+---
+
+## 3. Arquitectura del Despliegue en el Cliente (Modelo Hub & Spoke)
+
+Cuando vendemos e instalamos Evolith en una corporación, la arquitectura de gobierno funciona bajo un modelo centralizado de "Hub y Satélites", separando claramente dónde *nacen* las reglas y dónde se *ejecutan*.
+
+### A. La Fuente de la Verdad (El Repositorio Central)
+Se crea un único repositorio en la empresa, por convención llamado **`[empresa]-evolith-core`** o **`architecture-baseline`**.
+* Este repositorio actúa como la "Constitución" técnica. Aquí viven todos los ADRs (Markdown), Rulesets (JSON/YAML) y Políticas OPA (`.rego`).
+* Estas reglas se empaquetan en el contenedor del motor (Core API) y se ejecutan centralmente a velocidad de milisegundos gracias a la compilación a `policy.wasm`.
+* Solo los Arquitectos Empresariales tienen permisos para aprobar cambios en este repositorio.
+
+### B. Los Consumidores (Repositorios Satélites)
+Los cientos de repositorios de producto o microservicios que tienen los desarrolladores se denominan **satélites**.
+* Estos repositorios **no contienen las reglas**.
+* Cuando el programador en un satélite ejecuta `evolith validate`, el CLI consulta remotamente el motor del repositorio central.
+* **Ventaja competitiva:** Si la empresa actualiza un estándar de seguridad en el repositorio `[empresa]-evolith-core`, automáticamente todos los repositorios satélites de la organización comienzan a ser auditados bajo la nueva regla, sin tener que hacer actualizaciones manuales en 500 proyectos distintos.
+
+---
+
+## 4. Evolución y Adaptabilidad (Future-Proofing)
+
+La tecnología cambia rápido. Lo que hoy es un estándar, mañana queda obsoleto. ¿Cómo sobrevive Evolith a la aparición de nuevas topologías (ej. Agentic AI, Data Mesh)?
+
+* **Motor Agnóstico:** La magia de Evolith es que **no tiene arquitecturas específicas quemadas (hardcoded) en su código**. El motor solo sabe procesar reglas abstractas. Si la empresa quiere adoptar un nuevo patrón, solo añade una nueva carpeta con reglas en el repositorio central, y el motor aprende a evaluarlo instantáneamente.
+* **El Eje Progresivo (Progressive Axis):** Evolith no asume que todos los proyectos son Microservicios perfectos. Permite mapear reglas evolutivas: desde un MVP rápido, pasando por un Monolito Modular, hasta servicios distribuidos, aplicando las reglas justas según la etapa de madurez del producto.
+
+### Ingesta de Nuevo Conocimiento (Automatización y GitOps)
+Actualizar estas reglas no es un trabajo manual y tedioso; está automatizado en las 3 interfaces:
+1. **La Vía de la IA (Servidor MCP):** El servidor MCP es bidireccional. Un agente de IA autorizado puede analizar una nueva tendencia en la industria, redactar automáticamente un borrador de ADR y un archivo `.rego`, y proponer un *Pull Request* en el repositorio central.
+2. **La Vía del Desarrollador (CLI):** El CLI cuenta con herramientas de *scaffolding* (ej. `evolith adr create`) que generan toda la estructura base para añadir un nuevo estándar en segundos.
+3. **La Vía de Infraestructura (GitOps):** Al aprobarse un *Pull Request* en el repositorio central corporativo, la infraestructura se actualiza vía *Webhooks*. El motor Core API descarga las nuevas políticas compiladas y hace un **hot-reload** (recarga en caliente), actualizando el cerebro de la empresa sin interrupciones en el servicio.
+
+---
+
+## 5. El Modelo de Monetización: Evolith Tracker (Enterprise)
+
+Mientras que Evolith Core resuelve el problema del desarrollador individual en su repositorio (visión táctica), el CTO y los Directores de Ingeniería tienen un problema mayor (visión estratégica).
+
+Aquí es donde entra **Evolith Tracker**, nuestro producto comercial.
+
+### El Cierre de la Venta:
+Una vez que el cliente tiene Evolith Core corriendo en 50 proyectos distintos (satélites), el CTO se enfrenta a un punto ciego corporativo:
+* *"¿Cómo sé cuáles de nuestros 50 proyectos están cumpliendo la arquitectura central y cuáles son un riesgo?"*
+* *"¿Cómo administro reglas distintas para la División de Pagos y la División de Logística?"*
+
+**Evolith Tracker se vende como el Centro de Control Corporativo (Control Plane):**
+* **Observabilidad Global:** Dashboards ejecutivos con el "Maturity Report" de toda la organización.
+* **Multi-Tenancy:** Gestión centralizada de políticas, inquilinos (tenants) y repositorios.
+* **Gestión de Excepciones:** Flujos de aprobación visual para cuando un equipo necesita romper una regla por una emergencia de negocio.
+* **Trazabilidad del ROI:** Gráficos que demuestran a la gerencia cómo la deuda técnica está disminuyendo a lo largo del tiempo gracias a Evolith Core.
+
+---
+
+## 6. Resumen de la Estrategia (Product-Led Growth)
+
+1. **Atraer (Seed):** Distribuimos Evolith Core gratis. Los equipos técnicos lo instalan por el inmenso valor de automatizar las validaciones de arquitectura y gobernar a sus Agentes de IA vía MCP.
+2. **Expandir (Land):** Evolith se vuelve el estándar de facto en los pipelines CI/CD de la empresa. La arquitectura de los satélites se ancla al repositorio central (`[empresa]-evolith-core`), evoluciona dinámicamente y deja de degradarse.
+3. **Monetizar (Expand):** Le vendemos **Evolith Tracker** a los tomadores de decisión (CTOs/Enterprise Architects) que necesitan visibilidad, reportes agregados y control centralizado de los cientos de nodos de Evolith Core desplegados en su ecosistema.
diff --git a/product/suite/vision/evolith-commercial-brochure.md b/product/suite/vision/evolith-commercial-brochure.md
new file mode 100644
index 000000000..1a999e588
--- /dev/null
+++ b/product/suite/vision/evolith-commercial-brochure.md
@@ -0,0 +1,83 @@
+# Evolith: Commercial Narrative and Product Strategy
+
+> **Core Vision:** Evolith is an executable architectural governance framework. We democratize *how* software is structured (Open Source), but we commercialize enterprise *observability and control* (Evolith Tracker).
+
+---
+
+## 1. The Problem (The Market Pain)
+
+Companies invest thousands of dollars in software architects to design robust systems and write Architecture Decision Records (ADRs). However, the operational reality is different:
+* **Documentation dies:** ADRs live in static wikis that no one consults during development.
+* **Silent degradation:** With staff turnover and the pressure to deliver fast (and now, with AI agents generating code at high speed), the architecture deviates from the original design (Architecture Drift).
+* **Uncontrollable Technical Debt:** By the time management realizes the mess, refactoring the system is expensive and paralyzes the business.
+
+## 2. The Baseline Solution: Evolith Core (Open Source)
+
+**Evolith Core** transforms architecture rules from simple "text documents" into **executable code**.
+
+* **For the Developer:** It works like an architectural linter. With a simple `evolith validate` in their CLI, they know in seconds if their code complies with the rules.
+* **For AI Agents:** Through the MCP Server, agents like Claude or Cursor instantly understand the company's standards before writing a single line of code.
+* **For the Pipeline (CI/CD):** It acts as an automated security guard, blocking any *Pull Request* that attempts to introduce architecture violations (Phase Gates).
+
+> [!TIP]
+> **The Adoption Strategy (The Trojan Horse):** Evolith Core is **free and Open Source**. The goal is for developers and technical leads to adopt it massively because it reduces friction, speeds up code-reviews, and improves the quality of their daily work.
+
+---
+
+## 3. Client Deployment Architecture (Hub & Spoke Model)
+
+When we sell and install Evolith in a corporation, the governance architecture operates under a centralized "Hub and Satellite" model, clearly separating where rules are *born* and where they are *executed*.
+
+### A. The Source of Truth (The Central Repository)
+A single repository is created in the company, conventionally named **`[company]-evolith-core`** or **`architecture-baseline`**.
+* This repository acts as the technical "Constitution". All ADRs (Markdown), Rulesets (JSON/YAML), and OPA Policies (`.rego`) live here.
+* These rules are packaged in the engine container (Core API) and executed centrally at millisecond speeds thanks to compilation to `policy.wasm`.
+* Only Enterprise Architects have permissions to approve changes in this repository.
+
+### B. The Consumers (Satellite Repositories)
+The hundreds of product or microservice repositories that developers have are called **satellites**.
+* These repositories **do not contain the rules**.
+* When a programmer in a satellite runs `evolith validate`, the CLI remotely queries the central repository's engine.
+* **Competitive Advantage:** If the company updates a security standard in the `[company]-evolith-core` repository, all satellite repositories in the organization automatically start being audited under the new rule, without having to make manual updates in 500 different projects.
+
+---
+
+## 4. Evolution and Adaptability (Future-Proofing)
+
+Technology changes fast. What is a standard today is obsolete tomorrow. How does Evolith survive the emergence of new topologies (e.g., Agentic AI, Data Mesh)?
+
+* **Agnostic Engine:** Evolith's magic is that **it has no specific architectures hardcoded in its code**. The engine only knows how to process abstract rules. If the company wants to adopt a new pattern, it just adds a new folder with rules in the central repository, and the engine learns to evaluate it instantly.
+* **The Progressive Axis:** Evolith does not assume that all projects are perfect Microservices. It allows mapping evolutionary rules: from a fast MVP, to a Modular Monolith, to distributed services, applying the right rules according to the product's maturity stage.
+
+### Ingestion of New Knowledge (Automation and GitOps)
+Updating these rules is not a tedious, manual job; it is automated across the 3 interfaces:
+1. **The AI Path (MCP Server):** The MCP server is bidirectional. An authorized AI agent can analyze a new industry trend, automatically draft an ADR and a `.rego` file, and propose a *Pull Request* in the central repository.
+2. **The Developer Path (CLI):** The CLI has *scaffolding* tools (e.g., `evolith adr create`) that generate the entire base structure to add a new standard in seconds.
+3. **The Infrastructure Path (GitOps):** When a *Pull Request* is approved in the central corporate repository, the infrastructure updates via *Webhooks*. The Core API engine downloads the newly compiled policies and performs a **hot-reload**, updating the company's brain without service interruptions.
+
+---
+
+## 5. The Monetization Model: Evolith Tracker (Enterprise)
+
+While Evolith Core solves the individual developer's problem in their repository (tactical vision), the CTO and Engineering Directors have a bigger problem (strategic vision).
+
+This is where **Evolith Tracker**, our commercial product, comes in.
+
+### Closing the Sale:
+Once the client has Evolith Core running in 50 different projects (satellites), the CTO faces a corporate blind spot:
+* *"How do I know which of our 50 projects are complying with the central architecture and which are a risk?"*
+* *"How do I manage different rules for the Payments Division and the Logistics Division?"*
+
+**Evolith Tracker is sold as the Corporate Control Center (Control Plane):**
+* **Global Observability:** Executive dashboards with the "Maturity Report" of the entire organization.
+* **Multi-Tenancy:** Centralized management of policies, tenants, and repositories.
+* **Exception Management:** Visual approval workflows for when a team needs to break a rule due to a business emergency.
+* **ROI Traceability:** Charts demonstrating to management how technical debt is decreasing over time thanks to Evolith Core.
+
+---
+
+## 6. Strategy Summary (Product-Led Growth)
+
+1. **Seed:** We distribute Evolith Core for free. Technical teams install it for the immense value of automating architecture validations and governing their AI Agents via MCP.
+2. **Land:** Evolith becomes the de facto standard in the company's CI/CD pipelines. The architecture of the satellites anchors to the central repository (`[company]-evolith-core`), evolves dynamically, and stops degrading.
+3. **Expand:** We sell **Evolith Tracker** to decision-makers (CTOs/Enterprise Architects) who need visibility, aggregated reports, and centralized control of the hundreds of Evolith Core nodes deployed in their ecosystem.