From 490ec589d7f288e5b0c36635601fb1b07ab80f0c Mon Sep 17 00:00:00 2001 From: aarroyo Date: Sun, 16 Aug 2026 17:29:14 -0500 Subject: [PATCH] docs(readme): rebuild the landing surface around commands that now run The README opened with a menu, an architecture diagram and a link to a quickstart whose Step 1 invoked a script that does not exist. The working quickstart sat at line 227 of 389, behind a twenty-row Q and A accordion. Measured readership over the preceding fortnight: two unique visitors to the landing page. WHAT A STRANGER NOW SEES FIRST: a one-line positioning claim, one badge row, and an installable three-command block at line 16. Then the section that does the work. 'What just happened' quotes a REAL run of the published 1.3.0 in a container with nothing but Node -- 133 checked / 26 skipped / 0 errored, 37 blocking, exit 2 -- and then says the thing the numbers are for: NINE of those 37 blocking issues are rules that were SKIPPED. Not rules that failed; rules the engine could not decide, reported as failures because an undecided blocking rule is not a passing one. Backed by a named invariant test rather than by adjectives. Added 'Use it as a PR gate' with the copyable block. The README mentioned the GitHub Action NOWHERE, while action.yml has been Marketplace-shaped at the repository root for weeks. Added 'Why not ArchUnit, Conftest or dependency-cruiser?' -- which opens by telling the reader to use them. It also states what is NOT built: no command in the installed CLI reaches an LLM, so the 'LLM proposes, verifier disposes' half is a documented direction and is labelled as one. That paragraph exists because it is the first thing a skeptic greps for. The Q and A accordion moves below Quick Start and the hero diagram below the fold. Convince with the terminal; reward with the diagram. NUMBERS, AND I HAD TWO OF THEM WRONG. The README claimed '137 ADRs, 163 rulesets, 45 schemas' and '47 tools, 9 resources'. My own first count said 103 core ADRs and 382 rules. An independent measurement replicating the production loader corrected both: the normalizer reads , so the corpus is 412 rules and not 382, and 142 is the ADR count once README/adr-matrix/authoring-standard are excluded. Now: 142 ADRs, 181 ruleset files carrying 412 rules, 50 schemas, 52 tools, 12 resources. It also caught a contradiction I had introduced: 412 is the corpus the Core carries, 159 is what one satellite's run selected. The README now says which is which, because a report that blurred two denominators is the exact defect this project exists to stop. QUICKSTART REWRITTEN. It made booting a Core API a mandatory Step 1 via ./.harness/scripts/run-core-local.sh -- a file that does not exist -- and promised a server on :30080 that no service in the compose file defines. It is now the three commands that work, plus what the numbers mean and the exit-code taxonomy. The server material moved to a new 'Self-hosting the Core API' guide that opens by saying you do not need it, and that records the dead instruction rather than quietly deleting it. Also fixed the dead 'Onboarding by role' table row -- plain text where a link belonged. --- README.es.md | 230 ++++++++++++++++-------- README.md | 228 +++++++++++++++-------- docs/guides/evolith-quickstart.es.md | 95 +++++----- docs/guides/evolith-quickstart.md | 91 +++++----- docs/guides/self-hosting-core-api.es.md | 46 +++++ docs/guides/self-hosting-core-api.md | 46 +++++ 6 files changed, 509 insertions(+), 227 deletions(-) create mode 100644 docs/guides/self-hosting-core-api.es.md create mode 100644 docs/guides/self-hosting-core-api.md diff --git a/README.es.md b/README.es.md index a778599e..eda93b12 100644 --- a/README.es.md +++ b/README.es.md @@ -1,28 +1,106 @@
-# Evolith: Framework de Gobernanza Arquitectónica Ejecutable +# Evolith Core > **Navegación Bilingüe:** [English](./README.md) -[![Status](https://img.shields.io/badge/Status-Activo-brightgreen?style=for-the-badge)]() -[![Method](https://img.shields.io/badge/Method-Spec--driven_AI--DD-blueviolet?style=for-the-badge)]() -[![License](https://img.shields.io/badge/License-MIT-informational?style=for-the-badge)]() -[![CI](https://img.shields.io/github/actions/workflow/status/beyondnetcode/evolith_arch32/docs.yml?style=for-the-badge&label=CI)](https://github.com/beyondnetcode/evolith_arch32/actions) +[![npm](https://img.shields.io/npm/v/@beyondnet/evolith-cli?label=%40beyondnet%2Fevolith-cli)](https://www.npmjs.com/package/@beyondnet/evolith-cli) +[![CI](https://img.shields.io/github/actions/workflow/status/beyondnetcode/evolith_arch32/ci-cd.yml?branch=main&label=CI)](https://github.com/beyondnetcode/evolith_arch32/actions/workflows/ci-cd.yml) +[![License](https://img.shields.io/badge/license-MIT-informational)](./LICENSE) -> **[Empieza aquí: instala el CLI y lanza tu primera comprobación](#inicio-rápido)** — tres comandos, sin levantar ningún servidor. +**Gobernanza de arquitectura ejecutable. Una regla que no se evaluó no es una regla que pasó.** -
+
- - Visión General del Producto Evolith E2E — Composición Gobernada, Core de evaluación stateless, SDLC federado de cinco fases - +```bash +npm install -g @beyondnet/evolith-cli +evolith init --name my-sat --yes +evolith validate --engine opa +``` -↑ Visión General del Producto Evolith E2E · Abrir visor interactivo — arrastra para desplazar · rueda para zoom · pantalla completa · Ctrl/⌘+clic para nueva pestaña +[Inicio Rápido](#inicio-rápido) · [Atlas interactivo de arquitectura](https://beyondnetcode.github.io/evolith_arch32/) · [Cómo auditamos nuestras propias afirmaciones](./reference/core/control-center/adoption/pending-2026-08-16.md) - +--- + +## Qué acaba de pasar + +Ese tercer comando evaluó el corpus de reglas de este propio repositorio contra un satélite +recién inicializado, usando el bundle Rego compilado. Salida real de +`@beyondnet/evolith-cli@1.3.0` en un contenedor con nada más que Node instalado: + +``` +Rules: 133 checked / 26 skipped / 0 errored / 159 total +37 blocking issue(s) +exit code 2 + + 26 rule(s) were NOT evaluated - their result is UNKNOWN, not passed. +``` + +El Core carga **412 reglas**; el 159 de arriba es lo que la ejecución de este satélite +seleccionó de ellas. Dos denominadores distintos, y un informe que los mezclara sería el +defecto exacto que este proyecto existe para evitar. + +**Nueve de esos 37 issues bloqueantes son reglas que se saltaron.** No reglas que fallaron: +reglas que el motor no pudo decidir, reportadas como fallo porque una regla bloqueante sin +decidir no es una regla que pasa. Entre ellas están `SEC-INJ-01`, `SEC-INJ-02` y `SEC-PATH-01`. + +Esta es la idea entera. Todo linter de arquitectura y de políticas pasa en silencio las reglas +que nunca evaluó, con lo que *cobertura* y *cumplimiento* producen el mismo verde. Evolith +publica el denominador y se niega a redondearlo hacia arriba: + +- El bundle compilado declara qué ids de regla puede decidir, y `skipped` es un resultado de + primera clase, no la ausencia de una violación. +- Una regla bloqueante que termina `skipped` hace fallar la ejecución. Ese invariante tiene su + propio test, escrito contra el código que no lo tenía: + [`blocking-skipped-invariant.spec.ts`](./src/packages/core-domain/src/application/validators/blocking-skipped-invariant.spec.ts). +- Dos motores -- un evaluador nativo en TypeScript y Rego/WASM -- deben coincidir sobre + fixtures, o el CI falla. + +Los códigos de salida son una taxonomía, no un booleano: `0` pasa, `1` la herramienta falló, +`2` la puerta bloqueó, `3` la invocaste mal. Una ejecución que no pudo producir un veredicto +nunca reporta uno. + +--- + +## Úsalo como puerta de PR + +```yaml +- uses: beyondnetcode/evolith_arch32@v1 + with: + fail-on-violation: true +``` + +Expone `compliance-status`, `violations-count`, `issues-count`, `exit-code` y `report-path`. +`error` e `invalid-input` significan que el repositorio **no fue evaluado** -- no son formas +más débiles de no-conforme, y el resumen del job lo dice con palabras. + +Como contexto vivo para un agente de IA, sobre stdio: + +```json +{ "mcpServers": { "evolith": { "command": "npx", "args": ["-y", "@beyondnet/evolith-mcp"] } } } +``` + +--- + +## Por qué no ArchUnit, Conftest o dependency-cruiser + +Úsalos. Son buenos, y Evolith no sustituye a ninguno. + +| Herramienta | Qué hace bien | En qué difiere Evolith | +|---|---|---| +| **ArchUnit / ts-arch** | Reglas de capas y dependencias como tests unitarios, en tu lenguaje | Las reglas viven fuera del código como datos, así que un mismo corpus gobierna muchos repositorios y un agente puede leerlo | +| **Conftest / OPA** | Rego contra cualquier entrada estructurada | Evolith *es* OPA por debajo. Lo que añade es el corpus, la derivación de ADR a regla, y la contabilidad de cobertura | +| **dependency-cruiser** | Reglas sobre el grafo de dependencias, rápido y enfocado | Corpus más amplio (gates SDLC, topologías, estándares de seguridad) y un rastro de evidencia por veredicto | +| **Backstage Scorecards** | Chequeos de salud sobre todo el catálogo, con UI | Corre offline en CI sin catálogo que mantener, y bloquea un PR en vez de colorear un panel | + +**En qué es genuinamente distinto:** reporta lo que no pudo evaluar. Ninguna de las +herramientas de arriba distingue "esta regla pasó" de "esta regla nunca corrió" en su código +de salida. + +**Qué NO está construido todavía, para que no lo descubras tú:** la mitad de "el LLM propone, +un verificador determinista dispone" es una dirección documentada, no comportamiento +publicado. Ningún comando del CLI instalado alcanza un LLM. Ver +[Egreso de Red y Manejo de Datos](#egreso-de-red-y-manejo-de-datos). --- @@ -30,13 +108,13 @@ - [¿Qué es Evolith?](#qué-es-evolith) - [¿Por qué Evolith?](#por-qué-evolith) -- [Preguntas y Respuestas](#preguntas-y-respuestas) - [Conceptos Clave](#conceptos-clave) - [Ecosistema de Productos](#ecosistema-de-productos) - [Cómo Funciona](#cómo-funciona) - [Visión de Arquitectura](#visión-de-arquitectura) - [Componentes Principales](#componentes-principales) - [Inicio Rápido](#inicio-rápido) +- [Preguntas y Respuestas](#preguntas-y-respuestas) - [Egreso de Red y Manejo de Datos](#egreso-de-red-y-manejo-de-datos) - [Documentación](#documentación) - [Casos de Uso](#casos-de-uso) @@ -67,59 +145,6 @@ Evolith hace que la gobernanza sea **ejecutable**: --- -## Preguntas y Respuestas - -
-¿Qué es Evolith en una frase? -
-Evolith es un framework ejecutable de gobernanza arquitectónica — se asegura de que las decisiones de arquitectura realmente se cumplan, automáticamente, ya sea que el código lo escriba un humano o un agente AI. -
- -
-¿Para qué lo usaría? -
-
    -
  1. Feedback instantáneo en decisiones arquitectónicas — ejecuta evolith validate y sabe en segundos si tu código cumple.
    2. -
  2. Sin refactors sorpresa — el drift arquitectónico se detecta en el gate, no seis meses después.
    3. -
  3. Gobernanza a prueba de AI — cuando un agente AI escribe código, Evolith asegura que siga las mismas reglas que un arquitecto senior.
    4. -
-
- -
-¿Cuánto cuesta? -
-La plataforma core es completamente gratis (licencia MIT): CLI, servidor MCP, Core API, Agent Runtime, 137 ADRs, 163 rulesets, 45 schemas. El único producto de pago es Evolith Tracker (gobernanza enterprise multi-tenant — aún no lanzado). -
- -
-¿Cómo empiezo? -
- -```bash -npm install -g @beyondnet/evolith-cli -evolith init --name my-sat --yes # inicializa el directorio ACTUAL -evolith validate # mismo directorio, sin `cd` -``` - -Sin base de datos, sin servidor, sin Docker. -
- -
-¿Qué topologías cubre? -
-Evolith gobierna 8 topologías en 5 dimensiones: Modular Monolith, Distributed Modules, Microservices (progressive-axis), Serverless, Edge Computing (execution), Event-Driven (integration), Data Mesh (data) y Agentic AI. Todas componibles. -
- -
-¿Cómo funciona con herramientas AI como Cursor o Claude? -
-Evolith envía un servidor MCP dentro del CLI. Agrégalo a la configuración de tu herramienta AI y tu agente puede consultar reglas, validar código y evaluar gates — todo gobernado. -
- -**[Q&A completo: 64 preguntas en 12 categorías →](./reference/core/sdlc/q-and-a.es.md)** - ---- - ## Conceptos Clave | Concepto | Qué es | @@ -147,7 +172,7 @@ Evolith se distribuye como una suite de productos coordinados sobre una base com | **[Evolith Core](reference/README.es.md)** | Constitución neutral al proveedor: principios, ADRs, rulesets, topologías y contratos | | **[Evolith CLI](product/products/smart-cli/README.es.md)** | Aplicación local — valida código, ejecuta compuertas, gestiona ADRs, sirve MCP | | **[Core API](product/products/core-api/README.es.md)** | Servicio REST para consultas y evaluación de gobernanza de forma remota | -| **[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) | +| **[MCP Services](product/products/mcp-services/README.es.md)** | Gobernanza como contexto en vivo para LLMs y agentes de IA (52 tools, 12 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) | @@ -189,6 +214,18 @@ Todos los productos comparten los mismos artefactos definidos en **Evolith Core* --- +
+ + + Visión General del Producto Evolith E2E - Composición Gobernada, Core de evaluación stateless, SDLC federado de cinco fases + + +Visión General del Producto Evolith E2E - Abrir visor interactivo - arrastra para desplazar, rueda para zoom, pantalla completa + +
+ ## Visión de Arquitectura Evolith gobierna **8 topologías** en cuatro ejes: @@ -266,6 +303,59 @@ Evolith CLI se configura mediante **`evolith.yaml`**; ejecuta `evolith --help` p --- +## Preguntas y Respuestas + +
+¿Qué es Evolith en una frase? +
+Evolith es un framework ejecutable de gobernanza arquitectónica — se asegura de que las decisiones de arquitectura realmente se cumplan, automáticamente, ya sea que el código lo escriba un humano o un agente AI. +
+ +
+¿Para qué lo usaría? +
+
    +
  1. Feedback instantáneo en decisiones arquitectónicas — ejecuta evolith validate y sabe en segundos si tu código cumple.
    2. +
  2. Sin refactors sorpresa — el drift arquitectónico se detecta en el gate, no seis meses después.
    3. +
  3. Gobernanza a prueba de AI — cuando un agente AI escribe código, Evolith asegura que siga las mismas reglas que un arquitecto senior.
    4. +
+
+ +
+¿Cuánto cuesta? +
+La plataforma core es completamente gratis (licencia MIT): CLI, servidor MCP, Core API, Agent Runtime, 142 ADRs, 181 ficheros de ruleset con 412 reglas, 50 schemas de phase-gate. El único producto de pago es Evolith Tracker (gobernanza enterprise multi-tenant — aún no lanzado). +
+ +
+¿Cómo empiezo? +
+ +```bash +npm install -g @beyondnet/evolith-cli +evolith init --name my-sat --yes # inicializa el directorio ACTUAL +evolith validate # mismo directorio, sin `cd` +``` + +Sin base de datos, sin servidor, sin Docker. +
+ +
+¿Qué topologías cubre? +
+Evolith gobierna 8 topologías en 5 dimensiones: Modular Monolith, Distributed Modules, Microservices (progressive-axis), Serverless, Edge Computing (execution), Event-Driven (integration), Data Mesh (data) y Agentic AI. Todas componibles. +
+ +
+¿Cómo funciona con herramientas AI como Cursor o Claude? +
+Evolith envía un servidor MCP dentro del CLI. Agrégalo a la configuración de tu herramienta AI y tu agente puede consultar reglas, validar código y evaluar gates — todo gobernado. +
+ +**[Q&A completo: 64 preguntas en 12 categorías →](./reference/core/sdlc/q-and-a.es.md)** + +--- + ## Egreso de Red y Manejo de Datos Evolith es local-first: la CLI, los rulesets, las políticas OPA y el Core de evaluación stateless corren en tu máquina, y tu código fuente nunca se sube — la evaluación ocurre donde está el código. Existe exactamente **una** integración de salida en todo el corpus, está **desactivada por defecto**, y esta es su divulgación completa. diff --git a/README.md b/README.md index ef8c55e8..150d1a5f 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,102 @@
-# Evolith: Executable Architectural Governance Framework +# Evolith Core > **Bilingual Navigation:** [Versión en Español](./README.es.md) -[![Status](https://img.shields.io/badge/Status-Active-brightgreen?style=for-the-badge)]() -[![Method](https://img.shields.io/badge/Method-Spec--driven_AI--DD-blueviolet?style=for-the-badge)]() -[![License](https://img.shields.io/badge/License-MIT-informational?style=for-the-badge)]() -[![CI](https://img.shields.io/github/actions/workflow/status/beyondnetcode/evolith_arch32/docs.yml?style=for-the-badge&label=CI)](https://github.com/beyondnetcode/evolith_arch32/actions) +[![npm](https://img.shields.io/npm/v/@beyondnet/evolith-cli?label=%40beyondnet%2Fevolith-cli)](https://www.npmjs.com/package/@beyondnet/evolith-cli) +[![CI](https://img.shields.io/github/actions/workflow/status/beyondnetcode/evolith_arch32/ci-cd.yml?branch=main&label=CI)](https://github.com/beyondnetcode/evolith_arch32/actions/workflows/ci-cd.yml) +[![License](https://img.shields.io/badge/license-MIT-informational)](./LICENSE) -> **[Start here: install the CLI and run your first check](#quick-start)** — three commands, no server to boot. +**Executable architecture governance. A rule that was not evaluated is not a rule that passed.** -
+
- - Evolith E2E Product Vision — Governed Composition, stateless evaluation Core, federated five-phase SDLC - +```bash +npm install -g @beyondnet/evolith-cli +evolith init --name my-sat --yes +evolith validate --engine opa +``` -↑ Evolith E2E Product Vision · Open interactive viewer — drag to pan · scroll to zoom · fullscreen · Ctrl/⌘+click for a new tab +[Quick Start](#quick-start) · [Interactive architecture atlas](https://beyondnetcode.github.io/evolith_arch32/) · [How we audit our own claims](./reference/core/control-center/adoption/pending-2026-08-16.md) - +--- + +## What just happened + +That third command evaluated this repository's own rule corpus against a freshly initialized +satellite, using the compiled Rego bundle. Real output, from `@beyondnet/evolith-cli@1.3.0` +in a container with nothing but Node installed: + +``` +Rules: 133 checked / 26 skipped / 0 errored / 159 total +37 blocking issue(s) +exit code 2 + + 26 rule(s) were NOT evaluated - their result is UNKNOWN, not passed. +``` + +The Core carries **412 rules**; the 159 above is what this one satellite's run selected from +them. Two different denominators, and a report that blurred them would be the exact defect +this project exists to stop. + +**Nine of those 37 blocking issues are rules that were skipped.** Not rules that failed -- +rules the engine could not decide, reported as failures because an undecided blocking rule +is not a passing one. Among them are `SEC-INJ-01`, `SEC-INJ-02` and `SEC-PATH-01`. + +This is the whole idea. Every architecture and policy linter silently passes the rules it +never evaluated, so *coverage* and *compliance* produce the same green. Evolith publishes the +denominator and refuses to round it up: + +- The compiled bundle declares which rule ids it can decide, and `skipped` is a first-class + outcome rather than the absence of a violation. +- A blocking rule that ends `skipped` fails the run. That invariant has its own test, written + against the code that did not have it: [`blocking-skipped-invariant.spec.ts`](./src/packages/core-domain/src/application/validators/blocking-skipped-invariant.spec.ts). +- Two engines -- a native TypeScript evaluator and Rego/WASM -- must agree on fixtures, or CI + fails. + +Exit codes are a taxonomy, not a boolean: `0` pass, `1` the tool failed, `2` the gate blocked, +`3` you invoked it wrong. A run that could not produce a verdict never reports one. + +--- + +## Use it as a PR gate + +```yaml +- uses: beyondnetcode/evolith_arch32@v1 + with: + fail-on-violation: true +``` + +Outputs `compliance-status`, `violations-count`, `issues-count`, `exit-code` and +`report-path`. `error` and `invalid-input` mean the repository was **not evaluated** -- they +are not weaker forms of non-compliant, and the job summary says so in words. + +As live context for an AI agent, over stdio: + +```json +{ "mcpServers": { "evolith": { "command": "npx", "args": ["-y", "@beyondnet/evolith-mcp"] } } } +``` + +--- + +## Why not ArchUnit, Conftest or dependency-cruiser? + +Use them. They are good, and Evolith is not a replacement for any of them. + +| Tool | What it does well | Where Evolith differs | +|---|---|---| +| **ArchUnit / ts-arch** | Layer and dependency rules as unit tests, in your language | Rules live outside the codebase as data, so the same corpus governs many repositories and an agent can read it | +| **Conftest / OPA** | Rego against any structured input | Evolith *is* OPA underneath. What it adds is the corpus, the ADR-to-rule derivation, and the coverage accounting | +| **dependency-cruiser** | Dependency graph rules, fast and focused | Broader corpus (SDLC gates, topologies, security standards), and an evidence trail per verdict | +| **Backstage Scorecards** | Catalog-wide health checks with a UI | Runs offline in CI with no catalog to maintain, and blocks a PR rather than colouring a dashboard | + +**Where it is genuinely different:** it reports what it could not evaluate. None of the tools +above distinguishes "this rule passed" from "this rule never ran" in their exit status. + +**What is not built yet, so you do not have to discover it:** the "LLM proposes, a +deterministic verifier disposes" half is a documented direction, not shipped behaviour. No +command in the installed CLI reaches an LLM. See [Network Egress and Data Handling](#network-egress-and-data-handling). --- @@ -30,13 +104,13 @@ - [What is Evolith?](#what-is-evolith) - [Why Evolith?](#why-evolith) -- [Questions & Answers](#questions--answers) - [Core Concepts](#core-concepts) - [Product Ecosystem](#product-ecosystem) - [How It Works](#how-it-works) - [Architecture Overview](#architecture-overview) - [Main Components](#main-components) - [Quick Start](#quick-start) +- [Questions & Answers](#questions--answers) - [Network Egress and Data Handling](#network-egress-and-data-handling) - [Documentation](#documentation) - [Use Cases](#use-cases) @@ -67,59 +141,6 @@ Evolith makes governance **executable**: --- -## Questions & Answers - -
-What is Evolith in one sentence? -
-Evolith is an executable architectural governance framework — it makes sure architecture decisions actually get followed, automatically, whether the code is written by a human or an AI agent. -
- -
-What would I use it for? -
-
    -
  1. Instant feedback on architecture decisions — run evolith validate and know in seconds if your code follows your team's rules.
    2. -
  2. No more surprise refactors — architecture drift is caught at the gate, not six months later.
    3. -
  3. AI-proof governance — when an AI agent writes code, Evolith ensures it follows the same rules a senior architect would enforce.
    4. -
-
- -
-How much does it cost? -
-The core platform is completely free (MIT license): CLI, MCP server, Core API, Agent Runtime, 137 ADRs, 163 rulesets, 45 schemas. The only paid product is Evolith Tracker (enterprise multi-tenant governance — not yet released). -
- -
-How do I get started? -
- -```bash -npm install -g @beyondnet/evolith-cli -evolith init --name my-sat --yes # initializes the CURRENT directory -evolith validate # same directory, no `cd` -``` - -No database, no server, no Docker required. -
- -
-What topologies does it cover? -
-Evolith governs 8 topologies across 5 dimensions: Modular Monolith, Distributed Modules, Microservices (progressive-axis), Serverless, Edge Computing (execution), Event-Driven (integration), Data Mesh (data), and Agentic AI. All are composable. -
- -
-How does it work with AI tools like Cursor or Claude? -
-Evolith ships an MCP server inside the CLI. Add it to your AI tool's config and your agent can query architecture rules, validate code, and evaluate gate readiness — all without bypassing governance. -
- -**[Full Q&A: 64 questions across 12 categories →](./reference/core/sdlc/q-and-a.md)** - ---- - ## Core Concepts | Concept | What it is | @@ -147,7 +168,7 @@ Evolith ships as a suite of coordinated products built on a common foundation. | **[Evolith Core](reference/README.md)** | Provider-neutral constitution: principles, ADRs, rulesets, topologies, and contracts | | **[Evolith CLI](product/products/smart-cli/README.md)** | Local enforcement — validate code, run gates, manage ADRs, serve MCP | | **[Core API](product/products/core-api/README.md)** | REST service for remote governance queries and evaluation | -| **[MCP Services](product/products/mcp-services/README.md)** | Governance as live context for LLMs and AI agents (47 tools, 9 resources, 8 prompts) | +| **[MCP Services](product/products/mcp-services/README.md)** | Governance as live context for LLMs and AI agents (52 tools, 12 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) | @@ -189,6 +210,18 @@ All products share the same artifacts defined in **Evolith Core**. --- +
+ + + Evolith E2E Product Vision - Governed Composition, stateless evaluation Core, federated five-phase SDLC + + +Evolith E2E Product Vision - Open interactive viewer - drag to pan, scroll to zoom, fullscreen + +
+ ## Architecture Overview Evolith governs **8 topologies** across four axes: @@ -266,6 +299,59 @@ Evolith CLI is configured via **`evolith.yaml`**; run `evolith --help` for the c --- +## Questions & Answers + +
+What is Evolith in one sentence? +
+Evolith is an executable architectural governance framework — it makes sure architecture decisions actually get followed, automatically, whether the code is written by a human or an AI agent. +
+ +
+What would I use it for? +
+
    +
  1. Instant feedback on architecture decisions — run evolith validate and know in seconds if your code follows your team's rules.
    2. +
  2. No more surprise refactors — architecture drift is caught at the gate, not six months later.
    3. +
  3. AI-proof governance — when an AI agent writes code, Evolith ensures it follows the same rules a senior architect would enforce.
    4. +
+
+ +
+How much does it cost? +
+The core platform is completely free (MIT license): CLI, MCP server, Core API, Agent Runtime, 142 ADRs, 181 ruleset files carrying 412 rules, 50 phase-gate schemas. The only paid product is Evolith Tracker (enterprise multi-tenant governance — not yet released). +
+ +
+How do I get started? +
+ +```bash +npm install -g @beyondnet/evolith-cli +evolith init --name my-sat --yes # initializes the CURRENT directory +evolith validate # same directory, no `cd` +``` + +No database, no server, no Docker required. +
+ +
+What topologies does it cover? +
+Evolith governs 8 topologies across 5 dimensions: Modular Monolith, Distributed Modules, Microservices (progressive-axis), Serverless, Edge Computing (execution), Event-Driven (integration), Data Mesh (data), and Agentic AI. All are composable. +
+ +
+How does it work with AI tools like Cursor or Claude? +
+Evolith ships an MCP server inside the CLI. Add it to your AI tool's config and your agent can query architecture rules, validate code, and evaluate gate readiness — all without bypassing governance. +
+ +**[Full Q&A: 64 questions across 12 categories →](./reference/core/sdlc/q-and-a.md)** + +--- + ## Network Egress and Data Handling Evolith is local-first: the CLI, the rulesets, the OPA policies and the stateless evaluation Core all run on your machine, and your source files are never uploaded — evaluation happens where the code is. There is exactly **one** outbound integration in the corpus, it is **off by default**, and this is its complete disclosure. @@ -332,7 +418,7 @@ Report a suspected egress or disclosure defect through the [Security Policy](./S | Agent Runtime | [Agent Runtime hub](./reference/core/architecture/foundations/README.md) | | Evolith Tracker | [Tracker hub](./product/products/evolith-tracker/README.md) | | Operations & SRE | [Operations hub](./product/operations/README.md) | -| Onboarding by role | Getting Started by Role | +| Onboarding by role | [Getting Started by Role](./reference/core/foundations/inheritance-model/product-quick-start.md) | | Ecosystem glossary | [Glossary](./reference/core/sdlc/glossary/glossary-ecosystem.md) | | Questions & Answers | [Q&A](./reference/core/sdlc/q-and-a.md) | | Gap tracking | [Gap Tracking Board](./reference/core/control-center/gaps/gap-tracking.md) | diff --git a/docs/guides/evolith-quickstart.es.md b/docs/guides/evolith-quickstart.es.md index 2492babe..2a5adc07 100644 --- a/docs/guides/evolith-quickstart.es.md +++ b/docs/guides/evolith-quickstart.es.md @@ -1,68 +1,77 @@ -# Guía de Inicio Rápido: Evolith (Paso a Paso) +# Inicio Rápido -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. +> **Navegación Bilingüe:** [English](./evolith-quickstart.md) ---- +Tres comandos. Sin servidor que arrancar, sin base de datos, sin clúster. -## Paso 1: Levantar el Cerebro (Evolith Core API) +## 1. Instalar -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 +npm install -g @beyondnet/evolith-cli ``` -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`. +El paquete instala dos binarios equivalentes: `evolith` (el nombre documentado) y +`evolith-cli`. Requiere Node 20. ---- +## 2. Inicializar un satélite -## Paso 2: Instalar el Cliente (Evolith CLI) +Un *satélite* es cualquier repositorio gobernado por un Core de Evolith. Inicializarlo escribe +un `evolith.yaml` en el directorio actual y nada más. -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 +evolith init --name my-sat --yes ``` -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: +`--yes` ejecuta sin prompts, algo que también implican un stdin no interactivo o `--format +json`. Para andamiar en un directorio nuevo, pásalo como posicional: +`evolith init my-sat --yes`. `--dry-run` no escribe nada. + +## 3. Validar + ```bash -export EVOLITH_CORE_URL="http://localhost:30080/api/v1" +evolith validate --engine opa ``` ---- +Salida real de `@beyondnet/evolith-cli@1.3.0` contra un satélite recién inicializado, en un +contenedor con nada más que Node: -## Paso 3: Tu Primera Validación +``` +Rules: 133 checked / 26 skipped / 0 errored / 159 total +37 blocking issue(s) +exit code 2 +``` -Ve a la carpeta raíz de cualquier proyecto de software (satélite) que quieras validar y ejecuta el comando de validación. +## Qué significan los números -```bash -cd mi-proyecto-backend -evolith validate -``` +**Espera hallazgos en la primera ejecución.** Un satélite recién inicializado es una línea +base, no un aprobado: muchas reglas asumen un repositorio más completo del que tiene un +proyecto en fase 0. -**¿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. +El número que importa es **skipped**. Esas 26 reglas no se evaluaron, así que su resultado es +*desconocido*, no *aprobado*. Nueve de los 37 issues bloqueantes son exactamente eso: reglas +que el motor no pudo decidir, reportadas como fallo en vez de redondearse hacia el verde. La +mayoría de linters no hace esta distinción, y por eso su cobertura y su cumplimiento se ven +idénticos. ---- +Los códigos de salida son una taxonomía, no un booleano: -## Paso 4: (Opcional) Conectar a tu Agente de IA +| Código | Significado | +|:---:|---| +| `0` | pasó | +| `1` | la herramienta falló -- no se produjo veredicto | +| `2` | la puerta bloqueó -- hay veredicto real, y dice que no | +| `3` | invocación inválida -- no se evaluó nada | -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. +`1` y `3` **no** son formas más débiles de `2`. Significan que tu repositorio nunca fue +examinado. -Para arrancar el servidor MCP, simplemente ejecuta: -```bash -evolith mcp start -``` +## Siguientes pasos -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. +- Acota lo que corre: `evolith rulesets` lista los packs, y `--select ` evalúa solo los + que nombres. No nombrar nada evalúa el corpus completo que carga este Core, reportado como + `selection.source: core-default`. +- Ponlo en CI: ver [Úsalo como puerta de PR](../../README.es.md#úsalo-como-puerta-de-pr). +- Sírvelo a un agente de IA: `npx -y @beyondnet/evolith-mcp` sobre stdio. +- Levanta tú el Core API -- solo hace falta para la superficie REST y escenarios + multi-repositorio, nunca para el CLI: + [Auto-hospedar el Core API](./self-hosting-core-api.es.md). diff --git a/docs/guides/evolith-quickstart.md b/docs/guides/evolith-quickstart.md index 6899ba04..6e8b1df3 100644 --- a/docs/guides/evolith-quickstart.md +++ b/docs/guides/evolith-quickstart.md @@ -1,68 +1,73 @@ -# Quickstart Guide: Evolith (Step by Step) +# Quickstart -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. +> **Bilingual Navigation:** [Versión en Español](./evolith-quickstart.es.md) ---- +Three commands. No server to boot, no database, no cluster. -## Step 1: Boot the Brain (Evolith Core API) +## 1. Install -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 +npm install -g @beyondnet/evolith-cli ``` -Once finished, the server will be listening on `http://localhost:30080`. You can view the generated API documentation at `http://localhost:30080/api/docs`. +The package installs two equivalent bins: `evolith` (the documented name) and `evolith-cli`. +Requires Node 20. ---- +## 2. Initialize a satellite -## Step 2: Install the Client (Evolith CLI) +A *satellite* is any repository governed by an Evolith Core. Initializing writes an +`evolith.yaml` into the current directory and nothing else. -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 +evolith init --name my-sat --yes ``` -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: +`--yes` runs without prompts, which is also implied by a non-TTY stdin or `--format json`. +To scaffold into a new directory instead, pass it positionally: `evolith init my-sat --yes`. +`--dry-run` writes nothing. + +## 3. Validate + ```bash -export EVOLITH_CORE_URL="http://localhost:30080/api/v1" +evolith validate --engine opa ``` ---- +Real output from `@beyondnet/evolith-cli@1.3.0` against a freshly initialized satellite, in a +container with nothing but Node: -## Step 3: Your First Validation +``` +Rules: 133 checked / 26 skipped / 0 errored / 159 total +37 blocking issue(s) +exit code 2 +``` -Navigate to the root folder of any software project (satellite) you want to validate and run the validation command. +## What the numbers mean -```bash -cd my-backend-project -evolith validate -``` +**Expect findings on the first run.** A freshly initialized satellite is a baseline, not a +pass: many rules assume a fuller repository than a phase-0 project has. -**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. +The number that matters is **skipped**. Those 26 rules were not evaluated, so their result is +*unknown* -- not *passed*. Nine of the 37 blocking issues are exactly that: rules the engine +could not decide, reported as failures rather than rounded up into the green. Most linters do +not draw this distinction, which is why their coverage and their compliance look identical. ---- +Exit codes are a taxonomy, not a boolean: -## Step 4: (Optional) Connect your AI Agent +| Code | Meaning | +|:---:|---| +| `0` | passed | +| `1` | the tool failed -- no verdict was produced | +| `2` | the gate blocked -- a real verdict, and it says no | +| `3` | invalid invocation -- nothing was evaluated | -Evolith isn't just for humans. You can connect your AI-powered code editor (Cursor, Claude Desktop, etc.) so it "understands" your architecture. +`1` and `3` are **not** weaker forms of `2`. They mean your repository was never examined. -To start the MCP server, simply run: -```bash -evolith mcp start -``` +## Next steps -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. +- Narrow what runs: `evolith rulesets` lists the packs, and `--select ` evaluates only + the ones you name. Naming nothing evaluates the whole corpus this Core carries, reported as + `selection.source: core-default`. +- Put it in CI: see [Use it as a PR gate](../../README.md#use-it-as-a-pr-gate). +- Serve it to an AI agent: `npx -y @beyondnet/evolith-mcp` over stdio. +- Run the Core API yourself -- only needed for the REST surface and multi-repository + scenarios, never for the CLI: [Self-hosting the Core API](./self-hosting-core-api.md). diff --git a/docs/guides/self-hosting-core-api.es.md b/docs/guides/self-hosting-core-api.es.md new file mode 100644 index 00000000..ce77fc96 --- /dev/null +++ b/docs/guides/self-hosting-core-api.es.md @@ -0,0 +1,46 @@ +# Auto-hospedar el Core API + +> **Navegación Bilingüe:** [English](./self-hosting-core-api.md) + +**No necesitas esto para usar el CLI.** `evolith validate` evalúa localmente contra el corpus +de rulesets empaquetado en el paquete npm; no abre ningún socket ni necesita servidor. Esta +guía es para la superficie REST y para escenarios multi-repositorio donde varios satélites +consultan un mismo Core gobernado. + +## Qué es + +El Core API es un servicio de evaluación stateless: recibe un contexto de evaluación y +devuelve un resultado. No almacena estado de producto, tenant ni iniciativa -- esos son +contexto, nunca entidades. + +## Ejecutarlo en local + +El fichero compose bajo `product/infra/` levanta los servicios de soporte (PostgreSQL y +compañía). Comprueba qué servicios declara de verdad antes de asumir un puerto: + +```bash +grep -nE '^ [a-z0-9-]+:' product/infra/docker-compose.yml +``` + +> **Esta guía afirmaba un arranque en un comando en `http://localhost:30080` vía +> `./.harness/scripts/run-core-local.sh`.** Ese script no existe, y ningún servicio del +> compose expone ese puerto. Fue durante meses la llamada a la acción más visible del +> repositorio. Si encuentras aquí otra instrucción que no funcione, es un defecto -- por favor +> abre un issue. + +Para un stack local completo incluyendo el Tracker, ver +[`product/infra/docker-compose.fullstack.yml`](../../product/infra/docker-compose.fullstack.yml). + +## Apuntar el CLI hacia él + +```bash +export EVOLITH_CORE_URL="http://localhost:30080/api/v1" +``` + +Solo tiene sentido cuando hay un Core API realmente escuchando en esa dirección. + +## Kubernetes + +Los charts de Helm viven bajo `product/infra/`. El direccionamiento cross-cluster tiene +trampas medidas (`host.docker.internal` no resuelve dentro de pods de kind, entre otras) -- +consulta las notas de infraestructura en vez de adivinar. diff --git a/docs/guides/self-hosting-core-api.md b/docs/guides/self-hosting-core-api.md new file mode 100644 index 00000000..73cb92c1 --- /dev/null +++ b/docs/guides/self-hosting-core-api.md @@ -0,0 +1,46 @@ +# Self-hosting the Core API + +> **Bilingual Navigation:** [Versión en Español](./self-hosting-core-api.es.md) + +**You do not need this to use the CLI.** `evolith validate` evaluates locally against the +ruleset corpus bundled in the npm package; it opens no socket and needs no server. This guide +is for the REST surface and for multi-repository scenarios where several satellites query one +governed Core. + +## What it is + +The Core API is a stateless evaluation service: it receives an evaluation context and returns +an evaluation result. It stores no product, tenant or initiative state -- those are context, +never entities. + +## Running it locally + +The compose file under `product/infra/` brings up the supporting services (PostgreSQL and +friends). Check which services it actually declares before assuming a port: + +```bash +grep -nE '^ [a-z0-9-]+:' product/infra/docker-compose.yml +``` + +> **This guide used to claim a one-command boot at `http://localhost:30080` via +> `./.harness/scripts/run-core-local.sh`.** That script does not exist, and no service in the +> compose file exposes that port. It was the repository's most prominent call to action for +> months. If you find another instruction here that does not run, it is a defect -- please +> open an issue. + +For a full local stack including the Tracker, see +[`product/infra/docker-compose.fullstack.yml`](../../product/infra/docker-compose.fullstack.yml). + +## Pointing the CLI at it + +```bash +export EVOLITH_CORE_URL="http://localhost:30080/api/v1" +``` + +Only meaningful once a Core API is actually listening on that address. + +## Kubernetes + +Helm charts live under `product/infra/`. Cross-cluster addressing has measured gotchas +(`host.docker.internal` does not resolve inside kind pods, among others) -- see the +infrastructure notes rather than guessing.