proyecto generalizado

docs/explicacion.md

@@ -1,4 +1,4 @@
-# AgentForge explicado de principio a fin
+# Forja explicado de principio a fin
 
 > **Para quién es esto.** Una guía didáctica para alguien que llega nuevo al
 > proyecto —técnico o no— y quiere entender *qué hace*, *por qué está hecho así*
@@ -18,7 +18,7 @@
 > opacos: prompts que cambian sin historial, validaciones inconsistentes, acciones
 > de alto impacto sin supervisión y ninguna auditoría de lo que decidió el agente.
 
-**AgentForge es el "plano de control" que pones *delante* de tus agentes** antes de
+**Forja es el "plano de control" que pones *delante* de tus agentes** antes de
 dejarlos tocar nada importante. No es un framework para *construir* agentes; es la
 capa que los **cataloga, versiona, valida, ejecuta de forma supervisada y audita**.
 
@@ -47,13 +47,13 @@ Si entiendes estas seis ideas, entiendes el proyecto. Todo lo demás son detalle
 
 ## 3. Vista de pájaro: dos servicios
 
-AgentForge son **dos procesos** que se hablan por HTTP/JSON:
+Forja son **dos procesos** que se hablan por HTTP/JSON:
 
 ```
 ┌───────────────────────────── docker-compose ──────────────────────────────┐
 │                                                                            │
 │   ┌──────────────────────┐      HTTP/JSON      ┌────────────────────────┐  │
-│   │  agentforge-dashboard │  ───────────────►   │   agentforge-core      │  │
+│   │  forja-dashboard │  ───────────────►   │   forja-core      │  │
 │   │  Streamlit   :8501    │  ◄───────────────   │   FastAPI    :8000     │  │
 │   │  (la "consola")       │                     │   (el cerebro)         │  │
 │   └──────────────────────┘                     └───────────┬────────────┘  │
@@ -69,9 +69,9 @@ AgentForge son **dos procesos** que se hablan por HTTP/JSON:
 └────────────────────────────────────────────────────────────────────────────┘
 ```
 
-- **`agentforge-core`** (FastAPI, puerto 8000) — todo el dominio: registry de
+- **`forja-core`** (FastAPI, puerto 8000) — todo el dominio: registry de
   agentes, motor de guardrails, runtime de ejecución, persistencia. No tiene UI.
-- **`agentforge-dashboard`** (Streamlit, puerto 8501) — una consola visual. **No
+- **`forja-dashboard`** (Streamlit, puerto 8501) — una consola visual. **No
   contiene lógica de negocio**: es un cliente HTTP del core con cinco páginas.
 
 La separación importa: el core podría servir a una CLI, a otro servicio, a un
@@ -97,7 +97,7 @@ pipeline... el dashboard es solo una de las caras posibles.
 
 ## 4. Recorrido por los módulos (y quién depende de quién)
 
-El código del core vive bajo `core/src/agentforge_core/`. Lo agrupo por capas, de
+El código del core vive bajo `core/src/ forja_core/`. Lo agrupo por capas, de
 las más internas (sin dependencias) a las más externas.
 
 ### 4.1 `domain/` — el vocabulario del sistema
@@ -278,7 +278,7 @@ inyectan). Dependen de él: la API (`api/executions.py` solo conoce el
 | `executions.py` | El más cargado: `POST /agents/{n}/invoke`, `GET /executions`, `GET /executions/{trace_id}`, `POST /executions/{trace_id}/approve`, `POST /executions/{trace_id}/reject`. Mantiene además `execution_index.json` (mapa `trace_id → agente/versión`) para poder reanudar tras un reinicio. |
 | `policies.py`, `violations.py` | Routers `/policies` y `/violations` (este con filtros por severidad, stage, etc.). |
 
-Y la **raíz de la app**: `core/src/agentforge_core/main.py` → `create_app()` instancia
+Y la **raíz de la app**: `core/src/ forja_core/main.py` → `create_app()` instancia
 `FastAPI`, añade el `TraceIdMiddleware`, monta los routers, y expone `/health`.
 
 Depende de: todo lo de arriba (vía `deps.py`). Dependen de él: el dashboard (por
@@ -297,7 +297,7 @@ HTTP) y los tests de integración (`tests/integration/`, vía `TestClient`).
 | `pages/5_📐_Politicas.py` | Inventario de políticas: validadores de entrada/salida (cada uno expandible con su config) y versiones. |
 | `components/` | Trozos reutilizables de UI: `diff_view` (pinta `+`/`-`/`@@`), `trace_view` (el timeline del `decision_path`), `violation_view` (badges de severidad). |
 
-Depende de: el `agentforge-core` por HTTP (vía `AGENTFORGE_CORE_URL`). **Nadie del
+Depende de: el `forja-core` por HTTP (vía `FORJA_CORE_URL`). **Nadie del
 core depende del dashboard.** No tiene tests unitarios (mal coste/beneficio para
 Streamlit); su verificación es la checklist manual de [`docs/manual_qa.md`](manual_qa.md).
 
@@ -464,7 +464,7 @@ sequenceDiagram
 
 ## 7. Persistencia: cuatro formas, cuatro razones
 
-AgentForge no usa una sola base de datos; usa la herramienta adecuada para cada cosa.
+Forja no usa una sola base de datos; usa la herramienta adecuada para cada cosa.
 
 | Qué | Cómo | Por qué así |
 |-----|------|-------------|
@@ -499,9 +499,9 @@ AgentForge no usa una sola base de datos; usa la herramienta adecuada para cada
 ## 9. Mapa del repositorio y por dónde empezar a leer
 
 ```
-agentforge/
+ forja/
 ├── core/
-│   ├── src/agentforge_core/
+│   ├── src/ forja_core/
 │   │   ├── domain/        ← los modelos de datos (empieza por execution.py)
 │   │   ├── config.py · observability/   ← cimientos transversales
 │   │   ├── llm/           ← proveedores LLM (Protocol + impls + factory)
@@ -512,7 +512,7 @@ agentforge/
 │   │   └── main.py        ← create_app(): ensambla la app
 │   ├── Dockerfile · requirements.txt
 ├── dashboard/
-│   ├── src/agentforge_dashboard/   ← Streamlit (client + app + pages + components)
+│   ├── src/ forja_dashboard/   ← Streamlit (client + app + pages + components)
 │   ├── Dockerfile · requirements.txt
 ├── agents/incident_analyzer/   ← el agente de ejemplo (YAMLs + escenarios .txt)
 ├── policies/default/           ← la política de guardrails de ejemplo